H2 database migration for Airlock IAM 7.6 or newer

This tutorial describes how to upgrade the H2 database when upgrading from Airlock IAM 7.5 or older to Airlock IAM 7.6 and newer.

 
Info

This tutorial is meant for the embedded H2 database in Airlock IAM. It may be applied mutatis mutandis to other types of H2 deployments as well.

Why and when the database migration is required

With Airlock 7.6 the embedded H2 database has been upgraded from version 1.4.197 to 2.1.210. The version change was necessary because of several severe security vulnerabilities in the old version.

The newer H2 version uses a different internal data format. The database itself must therefore be upgraded.

 
Notice

If using the embedded h2 database and upgrading from IAM 7.5 (or older) to IAM 7.6 (or newer), the database must be upgraded.

Data from old H2 databases cannot be read by IAM 7.6 or newer.

If you are not sure, whether the embedded H2 database is used, you may check if it gets started with Airlock IAM as follows:

  1. Open the file instance.properties in the instance directory.
    Example: less /home/airlock/iam/instances/auth/instance.properties
  2. Check if the value h2 is part of the list in property iam.modules.
  3. Alternatively, you may check the value of the properties by running the IAM command-line utility:
    Example: iam info -i auth | grep iam.modules

Prerequisites for the database migration

To perform the update, the following prerequisites must be met:

  • The IAM installation of the old IAM version (e.g. 7.5) must still be available.
  • The new IAM version (e.g. 7.6) must be installed.
  • The affected IAM instance must be stopped.

The table below lists all pieces of information required for the upgrade. To keep the instructions below valid for different IAM and h2 versions, it uses the variables shown in the following table. For each step, an example is given using the example values in the table.

The values in the example column are valid for a default IAM installation (e.g. using the installer) with instance auth. The h2 versions are valid when upgrading from IAM 7.5.2 to IAM 7.6.

VARIABLE

Meaning

Value used in example

H2_8.4.0_OLD

Refers to the H2 version found in the lib folder of the old IAM version.

Version 1.4.197 is valid for versions IAM 7.3 up to at least 7.5.2.

1.4.197

H2_8.4.0_NEW

Refers to the H2 version found in the lib folder of the new IAM version.

Version 2.1.210 is valid for IAM 7.6.

2.1.210

IAM_8.4.0_OLD

Refers to the absolute installation directory of the IAM binaries of the version before the upgrade.

/opt/airlock-iam-7.5.2

IAM_8.4.0_NEW

Refers to the absolute installation directory of the IAM binaries of the version after the upgrade.

/opt/airlock-iam-7.6

H2_DATA_DIR

Refers to the absolute h2 data directory. It is configured by property iam.h2.data.dir in the instance.properties file.

Alternatively it can be determined using the IAM command-line interface:
iam info -i <instance-name> | grep iam.h2.data.dir

Note that the iam.h2.data.dir is usually relative to the IAM base dir. Make sure to use the absolute path. The H2 script used below will not accept a relative path.

/home/airlock/iam/instances/auth/h2

H2_DB_NAME

Refers to the H2 database name. It is the last part of the JDBC URL that is configured by property ​​iam.h2.jdbc.url in the instance.properties file.
Alternatively the JDBC URL can be determined using the IAM command-line interface:
iam info -i <instance-name> | grep iam.h2.jdbc.url

Example: in the JDBC URL jdbc:h2:tcp://localhost:9001/iamdb the database name is iamdb.

iamdb

H2_USER

Refers to the database user that is used to connect to the H2 database. It is configured by property iam.h2.jdbc.user in the instance.properties file.

Alternatively it can be determined using the IAM command-line interface:
iam info -i <instance-name> | grep iam.h2.jdbc.user

airlock

H2_PASSWORD

Refers to the database password that is used to connect to the H2 database. It is configured by property iam.h2.jdbc.password in the instance.properties file.

password

BACKUP_DIR

Existing directory to move backup data during the migration. The directory must exist.

/home/airlock/

To use the example scripts below, you may use the following shell variables and set them to values matching your environment.

 
Example
H2_8.4.0_OLD=1.4.197
H2_8.4.0_NEW=2.1.210
IAM_8.4.0_OLD=/opt/airlock-iam-7.5.2
IAM_8.4.0_NEW=/opt/airlock-iam-7.6
H2_DATA_DIR=/home/airlock/iam/instances/auth/h2
H2_DB_NAME=iamdb
H2_USER=airlock
H2_PASSWORD=password
BACKUP_DIR=/home/airlock

Backup the database (using the old H2 library)

Back up the database using the old H2 library, as shown in the example script below.

 
Notice

Make sure to perform the step using the correct OS user such it has access to the H2 database files and to the installed IAM binaries. The user must be able to write files in a way that they are usable by Airlock IAM (ownership and permission).

In a standard IAM setup, that was created using the installer script, perform the steps as user airlock:
su - airlock

 
Example
# (1) remove, rename or move any backup files from previous database migrations from $BACKUP_DIR to avoid conflicts
# (2) backup database
$IAM_8.4.0_OLD/jre/bin/java -cp $IAM_8.4.0_OLD/lib/h2-$H2_8.4.0_OLD.jar org.h2.tools.Script \
   -url "jdbc:h2:file:$H2_DATA_DIR/$H2_DB_NAME" \
   -user $H2_USER \
   -password $H2_PASSWORD \
   -script $BACKUP_DIR/h2-backup.zip \
   -options compression zip

# (3) move away the h2 database files to avoid conflicts when restoring
mv $H2_DATA_DIR/$H2_DB_NAME* $BACKUP_DIR

Restore the database (using the new H2 library)

Restore up the database using the new H2 library, as shown in the example script below.

 
Example
# (4) restore database
 $IAM_8.4.0_NEW/jre/bin/java -cp $IAM_8.4.0_NEW/lib/h2-$H2_8.4.0_NEW.jar org.h2.tools.RunScript \
   -url "jdbc:h2:file:$H2_DATA_DIR/$H2_DB_NAME;NON_KEYWORDS=VALUE" \
   -user $H2_USER \
   -password $H2_PASSWORD \
   -script ~/h2-backup.zip \
   -options compression zip

Do not forget to start the IAM instance again.