IBM DB2 repository

This section makes the following assumptions about the DB2 environment. If these assumptions do not match your DB2 environment, adapt the subsequent instructions accordingly.

DB2 is running on the localhost, and is listening on the default port (50000).
The user db2inst1 is configured as the DB2 instance owner, and has the password Passw0rd1.

This section assumes that you will use basic username/password authentication. You can also configure Kerberos authentication with a DB2 repository.

Before you start, make sure that the server is stopped.

/path/to/openidm/shutdown.sh
OpenIDM is not running, not stopping.

Configure IDM to use the DB2 repository, as described in the following steps:

Create an OSGi bundle for the DB2 JDBC driver, as follows:
- Download the DB2 JDBC driver for your database version from the IBM download site and place it in the openidm/db/db2/scripts directory.
  
  Use either the db2jcc.jar or db2jcc4.jar, depending on your DB2 version. For more information, see the DB2 JDBC Driver Versions.
  ls /path/to/db/db2/scripts/ db2jcc.jar openidm.sql
- Create a bnd file and edit it to match the version information for your JDBC driver.
  
  You can use the sample bnd file located in openidm/db/mssql/scripts. Copy that file to the directory with the JDBC driver:
  cd /path/to/openidm/db cp mssql/scripts/sqljdbc4.bnd db2/scripts/ ls db2/scripts db2jcc.jar openidm.sql sqljdbc4.bnd
  The JDBC driver version information for your driver is located in the Specification-Version property in the MANIFEST file of the driver.
  cd /path/to/openidm/db/db2/scripts unzip -q -c db2jcc.jar META-INF/MANIFEST.MF Manifest-Version: 1.0 Created-By: 1.4.2 (IBM Corporation)
  Edit the bnd file to match the JDBC driver version:
  **more sqljdbc4.bnd** ... version=1.0 Export-Package: *;version=${version} Bundle-Name: IBM JDBC DB2 Driver Bundle-SymbolicName: com.ibm.db2.jcc.db2driver Bundle-Version: ${version}
- Download the most recent bnd JAR file from https://repo1.maven.org/maven2/biz/aQute/bnd/biz.aQute.bnd/. The bnd utility lets you create OSGi bundles for JDBC libraries that do not yet support OSGi.
  
  Place the bnd JAR file in the same directory as the JDBC driver:
  ls /path/to/openidm/db/db2/scripts biz.aQute.bnd-version.jar db2jcc.jar
- Change to the directory in which the script files are located and run the following command to create the OSGi bundle:
  cd /path/to/openidm/db/db2/scripts java -jar biz.aQute.bnd-version.jar wrap --properties sqljdbc4.bnd --output db2jcc-osgi.jar db2jcc.jar
  This command creates an OSGi bundle, as defined by the --output option: db2jcc-osgi.jar:
  ls /path/to/openidm/db/db2/scripts biz.aQute.bnd-version.jar db2jcc-osgi.jar db2jcc.jar
- Move the OSGi bundle fle to the openidm/bundle directory:
  mv db2jcc-osgi.jar /path/to/openidm/bundle/
Remove the default DS repository configuration file (repo.ds.json) from your project’s conf/ directory. For example:
```
cd /path/to/openidm/my-project/conf/
rm repo.ds.json
```
Copy the database connection configuration file for DB2 (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project’s configuration directory. For example:
```
cp /path/to/openidm/db/db2/conf/datasource.jdbc-default.json my-project/conf/
cp /path/to/openidm/db/db2/conf/repo.jdbc.json my-project/conf/
```

Update the connection configuration to reflect your DB2 deployment. The default connection configuration in the datasource.jdbc-default.json file is as follows:

{
    "driverClass" : "com.ibm.db2.jcc.DB2Driver",
    "jdbcUrl" : "jdbc:db2://&{openidm.repo.host}:&{openidm.repo.port}/dopenidm:retrieveMessagesFromServerOnGetMessage=true;",
    "databaseName" : "sopenidm",
    "username" : "openidm",
    "password" : "openidm",
    "connectionTimeout" : 30000,
    "connectionPool" : {
        "type" : "hikari",
        "minimumIdle" : 20,
        "maximumPoolSize" : 50
    }
}

Specify the values for openidm.repo.host and openidm.repo.port in one of the following ways:

Set in an IDM Properties File

Set the values in resolver/boot.properties or your project’s conf/system.properties file, for example:

openidm.repo.host = localhost
openidm.repo.port = 50000

Set as an Environment Variable

Set the properties in the OPENIDM_OPTS environment variable and export that variable before startup. You must include the JVM memory options when you set this variable. For example:

export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=50000"
/path/to/openidm/startup.sh -p my-project
Executing ./startup.sh...
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/openidm
Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=50000
Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
Using boot properties at /path/to/openidm/resolver/boot.properties
-> OpenIDM version "7.2.2"
OpenIDM ready

Create a user database for IDM (dopenidm).
```
db2 create database dopenidm
```
Import the IDM data definition language script into your DB2 instance.
```
cd /path/to/openidm
db2 -i -tf db/db2/scripts/openidm.sql
```
The database schema is defined in the SOPENIDM database.

You can show the list of tables in the repository, using the db2 list command, as follows:

db2 LIST TABLES for all
Table/View                      Schema          Type  Creation time
------------------------------- --------------- ----- --------------------------
CLUSTEROBJECTPROPERTIES         SOPENIDM        T     2015-10-01-11.58.05.968933
CLUSTEROBJECTS                  SOPENIDM        T     2015-10-01-11.58.05.607075
CONFIGOBJECTPROPERTIES          SOPENIDM        T     2015-10-01-11.58.01.039999
CONFIGOBJECTS                   SOPENIDM        T     2015-10-01-11.58.00.570231
GENERICOBJECTPROPERTIES         SOPENIDM        T     2015-10-01-11.57.59.583530
GENERICOBJECTS                  SOPENIDM        T     2015-10-01-11.57.59.152221
INTERNALUSER                    SOPENIDM        T     2015-10-01-11.58.04.060990
LINKS                           SOPENIDM        T     2015-10-01-11.58.01.349194
MANAGEDOBJECTPROPERTIES         SOPENIDM        T     2015-10-01-11.58.00.261556
MANAGEDOBJECTS                  SOPENIDM        T     2015-10-01-11.57.59.890152
...

Connect to the openidm database, and run the script that creates the tables required by the workflow engine:
```
db2 connect to dopenidm
db2 -i -tf /path/to/openidm/db/db2/scripts/flowable.db2.all.create.sql
```
If you plan to direct audit logs to this repository, run the script that sets up the audit tables:
```
db2 -i -tf /path/to/openidm/db/db2/scripts/audit.sql
```

When you have set up DB2 for use as the internal repository, make sure that the server starts without errors.

Kerberos authentication with a DB2 repository

By default, IDM uses the username and password configured in the repository connection configuration file (conf/datasource.jdbc-default.json) to connect to the DB2 repository. You can configure IDM to use Kerberos authentication instead.

In this scenario, IDM acts as a client and requests a Kerberos ticket for a service, which is DB2, through the JDBC driver.

This section assumes that you have configured DB2 for Kerberos authentication. If that is not the case, follow the instructions in the corresponding DB2 documentation before you read this section.

The following diagram shows how the ticket is obtained and how the keytab is referenced from IDM’s jaas.conf file.

Figure 1. Using Kerberos to Connect to a DB2 Repository

Configure IDM for Kerberos Authentication

Create a keytab file, specifically for use by IDM.

A Kerberos keytab file (krb5.keytab) is an encrypted copy of the host’s key. The keytab enables DB2 to validate the Kerberos ticket that it receives from IDM. You must create a keytab file on the host that IDM runs on. The keytab file must be secured in the same way that you would secure any password file. Specifically, only the user running IDM should have read and write access to this file.

Create a keytab for DB2 authentication, in the file openidm/security/idm.keytab/:
```
kadmin -p kadmin/admin -w password
kadmin: ktadd -k /path/to/openidm/security/idm.keytab db2/idm.example.com
```
Make sure that the DB2 user has read access to the keytab.
Copy the DB2 Java Authentication and Authorization Service (JAAS) configuration file to the IDM security directory:
```
cp /path/to/openidm/db/db2/conf/jaas.conf /path/to/openidm/security/
```
By default, IDM assumes that the keytab is in the file openidm/security/idm.keytab and that the principal identity is db2/idm.example.com@EXAMPLE.COM. Change the following lines in the jaas.conf file if you are using a different keytab:
```
keyTab="security/idm.keytab"
principal="db2/idm.example.com@EXAMPLE.COM"
```
Adjust the authentication details in your DB2 connection configuration file (conf/datasource.jdbc-default.json) to remove the password field and change the username to the instance owner (db2). The following excerpt shows the modified file:
```
{
    ...
    "databaseName" : "sopenidm",
    "username" : "db2",
    "connectionTimeout" : 30000,
    ...
}
```
Edit your project’s conf/system.properties file, to add the required Java options for Kerberos authentication.

In particular, add the following two lines to that file:
```
db2.jcc.securityMechanism=11
java.security.auth.login.config=security/jaas.conf
```
Restart IDM.