The upgrade procedure described in this section is applicable if you want to retain as much as possible from the configuration of the old Kernun UTM instance in the new instance. If you want to configure a new Kernun UTM version from scratch, follow the installation and configuration procedures described in Section 5, “Installation”.

Upgrading to a new version or build of Kernun UTM is basically done by restoring a backup of the old version in a system partition that contains a fresh installation of the new version. The upgrade procedure comprises the following steps:

The syntax and semantics of the configuration files are sometimes slightly changed between versions. In order to be usable in the new Kernun version, the old configuration file must be converted in step 1. This is done automatically during the upgrade process. The configuration conversion script expects the configuration in a normalized format. Using just some formatting accepted by normal Kernun configuration tools (GUI or CML) is not sufficient. The normalization during the upgrade process is done either automatically (by GUI), or using a command in the command line upgrade.

The upgrade operation results in a newly installed system partition that contains the new version of Kernun UTM. If we want to keep the configuration across upgrades, we need to copy the main Kernun UTM configuration file /usr/local/kernun/conf/kernun.cml and any other changes done in the old installation to the new one. The configuration files that have been changed, created, or deleted since the installation are found and saved when the old system partition is backed up in step 2.

Step 3 requires a full or patch installation image. Although it is possible to replace the contents of the currently used system partition with the new version, it is not recommended. You should always install an upgrade to a currently unused system partition, for two reasons. First, the old Kernun UTM instance can continue running until the upgrade is finished. Second, you can quickly return Kernun UTM to an operational state if something goes wrong with the upgrade.

Restoring of the backup from step 2 in the system partition installed in step 3 effectively copies the complete configuration from the old system partition. Restoring of a backup to a build different from the one used for its creation may cause conflicts. These are files that cannot be restored automatically and a manual intervention of the administrator is necessary. A conflict occurs if there are two incompatible changes of the same file. The original version of the file comes from the installation image of the Kernun UTM instance that is being upgraded; we will call it “old”. The second version (called “backed-up”) is contained in the backup file, if the file was changed^[10] at some time between the installation of the old version and the start of the upgrade process. The third version of the file (called “new”) is obtained from the installation image of the new Kernun UTM instance installed in step 3. There are two potential changes of the file. One between the old and the backed-up version, the second between the old and the new version. If only one change exists, no conflict occurs and the changed (backed-up or new) version of the file will be used. For example, /etc/ttys may have been changed by the administrator in the installed Kernun UTM, but remains the same in the build we are upgrading to. Another example is a proxy executable, which is modified in the new Kernun UTM version, but left unchanged by the administrator. If all three versions exist, i.e. when the backed-up and the new version differ, a conflict occurs. The automated upgrade tools are unable to handle the file and the administrator must decide whether the new file, the backed-up file, or some combination of the two should be used. For example, a third party software added in the new build creates a new user account in /etc/master.passwd, and the administrator has created another user account. During the upgrade, a conflict is reported for /etc/master.passwd. The administrator can resolve this particular conflict by merging the two versions of the file, adding both new user accounts to the resulting file.

The detected conflicts are recorded in the /data/restore/resolve file during step 4. The conflicting files from the backup file (the “backed-up” version) are not unpacked to the root directory tree. Instead, they are stored in corresponding locations under the /data/restore/conflicts directory. The root directory tree contains the files as installed (the “new” version). In step 5, the administrator specifies for each file how the conflict should be resolved, choosing from the following possibilities:

The /data/restore directory is deleted when all conflicts are resolved. Only one upgrade procedure can be in the conflict resolution stage at a time. If a conflict resolution session is started and there is already the /data/restore directory with unresolved conflicts, the administrator can either cancel the second resolution, or delete the old /data/restore directory, thus effectively using the “new” versions of the files for all conflicts in the earlier conflict resolution session.

In step 6, a script is executed that edits the contents of the main configuration file /usr/local/kernun/conf/kernun.cml to make it compatible with the upgraded Kernun UTM. Sometimes, if there are complex changes in the configuration syntax and semantics between the two Kernun UTM versions, or if the configuration file contains certain advanced constructs, the script may be unable to perform a perfect conversion. It is therefore recommended to always check the result of the automatic conversion in step 7.

The new configuration file needs to be applied before the upgraded system can be put into normal operation. The low-level configuration files are generated and the configuration is applied in the context of the newly installed system using the applycfg command of sysmgr(8). If the generation or application of the configuration fails, the configuration should be corrected and applied again.

Finally, the upgraded Kernun UTM can be put into the normal production mode by rebooting to the newly installed system partition.

No modifications of the configuration (steps 6 and 7) are often required during the upgrade procedure. This is usually true when upgrading between two builds of the same version or between patch releases of the same version, for example, from 3.0 to 3.0.1 or from 3.0.1 to 3.0.2.

7.1. Upgrade from the GUI

An upgrade is initiated from the Quick Wizards page of the System Manager. There are two alternatives. Click Upgrade Firewall if you want to start the complete upgrade procedure. If you already have a recent backup of the system partition that you want to upgrade, you can skip the first step — creation of a backup. In this case, use the Restore backup into newer firewall button. We will describe only the former alternative; the latter is almost identical, only the backup step is missing.

The GUI assumes that we want to upgrade the currently running Kernun UTM instance. Therefore, the current system partition will be backed up. After clicking on the Upgrade Firewall button, we select the target system partition in which the upgraded Kernun UTM will be installed. Then we select the installation image of the new version. Our selections are displayed in the settings recapitulation window (Figure 2.11, “Parameters of an upgrade operation”). Click on the Finish button to start the upgrade.

Figure 2.11. Parameters of an upgrade operation

The GUI displays the progress of the upgrade procedure. First, the current system partition is backed up. Then, the new system partition is installed and the backup is restored in it. If there are any conflicts, the conflict resolution window is displayed, as shown in Figure 2.12, “The conflict resolution window during an upgrade”. The window shows a list of conflicting files. You can determine how to resolve the conflict of a file by clicking in the Action column. The following actions are possible:

• + — uses the “backed-up“ version of the file;

• . — uses the “new” version of the file, as installed from the new installation image;

• - — deletes the file;

• ! — postpones the conflict to the next iteration of conflict resolution.

It is also possible to select a file and then click a button on the right-hand side of the window to display the differences between the two versions of the file, or to open one of them in an editor.

Figure 2.12. The conflict resolution window during an upgrade

After you give instructions for conflict resolution and optionally edit some conflicting files, click OK to have the conflicts resolved. Finally, a window is displayed (see Figure 2.13, “Final settings after an upgrade”) that makes it possible to realise any combination of the following actions: set the newly upgraded system partition as the default boot partition; run the configuration conversion script; change the partition label; reboot Kernun UTM immediately.

Figure 2.13. Final settings after an upgrade

[root@fw ~]# cml -l -f /usr/local/kernun/conf/kernun.cml 
RCSL-730-N File '/usr/local/kernun/conf/kernun.cml' locked for current user
CMLM-790-N RCS command completed
[root@fw ~]# sysmgr checkcfg 
...
Configuration is correct
[root@fw ~]# sysmgr backup 
Creating backup content database /kernun-backup.fsdb.bz2
Creating file system content database
Creating backup file
/data/backup/backup-030000h00.200809241501.i386-1-200811300006.tbz
[root@fw ~]# sysmgr install 2 030002h00.200811291341.i386 
Clearing system partition 2
...
Installation successfully finished
[root@fw ~]# sysmgr upgrade 2 \
> backup-030000h00.200809241501.i386-1-200811300006.tbz 
Processing changes of file system contents
Unpacking files from backup
Resolving conflicts
There are pending conflicts, see /data/restore/resolve


*** CONFLICT RESOLUTION *** 

1. Resolve with easy editor (ee)
2. Resolve with editor vi
3. Do not resolve now

Select action: 2
# Conflict resolution file for system partition /2 
# Each line of this file contains an instruction for one file. You
# can edit the file and then apply the instructions by running
# "sysmgr resolve". Every line contains three fields:
# - one character that defines an action to be done with the file
# - one character for file type ('d' for a directory, '-' for any
#   other type)
# - path to the file, interpreted either relative to /2 for the
#   existing file and relative to //data/restore/conflicts
#   for the file from the backup
# Procedure of conflict resolution:
# 1. Locate all lines beginning with '!'. These denote conflicting
#    files.
# 2. Optionally edit the conflicting files.
# 3. Change the character '!' to
#         + ... to use the file from backup, temporarily stored in
#               /data/restore/conflicts
#         . ... to keep the current file
#         - ... to delete the current file
#         ! ... keep the conflict for future resolution
# 4. Run "sysmgr resolve".
# 5. Repeat steps 1-4 until all conflicts are resolved.
# Merging file from the backup with the current file can be done
# either by editing the current file and specifying action '.'
# (keep) or editing the file from the backup and specifying
# action '+' (use backup).
! - ./etc/motd
! - ./etc/login.conf
...
Resolving conflicts
There are pending conflicts, see /data/restore/resolve 
[root@fw ~]# vi /data/restore/resolve 
...
[root@fw ~]# sysmgr resolve 
Resolving conflicts
All conflicts resolved
[root@fw ~]# sysmgr upgradecfg 2 
Upgrading Kernun configuration /2/usr/local/kernun/conf/kernun.cml
/2/usr/local/kernun/conf/kernun.cml,v  <--
  /2/usr/local/kernun/conf/kernun.cml
new revision: 1.2; previous revision: 1.1
done
Automatic configuration upgrade done. It is recommended to review the
configuration before returning Kernun UTM to production use.
[root@fw ~]# sysmgr applycfg 2 
...
System kernun applied in system partition 2
[root@fw ~]#  cml -u -f /usr/local/kernun/conf/kernun.cml 
CMLM-790-N RCS command completed
[root@fw ~]#