Follow these steps to install OpenIDM:

1. Make sure you have an appropriate version of Java installed:

   $ java -version
   java version "1.7.0_79"
   Java(TM) SE Runtime Environment (build 1.7.0_79-b15)
   Java HotSpot(TM) 64-Bit Server VM (build 24.79-b02, mixed mode)

   For a description of the Java requirements, see "Before You Install OpenIDM Software" in the Release Notes.

2. Download enterprise software releases through the ForgeRock BackStage site. ForgeRock enterprise releases are thoroughly validated builds for ForgeRock customers who run OpenIDM in production deployments, and for those who want to try or test with release builds.

3. Unpack the contents of the .zip file into the install location:

   $ cd /path/to
   $ unzip ~/Downloads/openidm-4.0.0.zip
   Archive:  openidm-4.0.0.zip
     inflating: openidm/.checksums.csv
      creating: openidm/bundle/
    extracting: openidm/bundle/openidm-audit-4.0.0.jar
   ...

4. (Optional) By default, OpenIDM listens for HTTP and HTTPS connections on ports 8080 and 8443, respectively. To change the default port, edit your project's conf/boot/boot.properties file. For more information, see "Ports Used" in the Integrator's Guide.

5. (Optional) Before running OpenIDM in production, replace the default OrientDB repository, provided for evaluation, with a supported JDBC repository.

   For more information, see "Installing a Repository For Production".

To run OpenIDM as a background process, see "Starting and Stopping OpenIDM" in the Integrator's Guide.

Follow these steps to run OpenIDM interactively:

1. Start the Felix container, load all OpenIDM services, and start a command shell to allow you to manage the container:

   • Start OpenIDM (UNIX):

     $ ./startup.sh
     
     Using OPENIDM_HOME:   /path/to/openidm
     Using PROJECT_HOME:   /path/to/openidm
     Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
     Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
     Using boot properties at /path/to/openidm/conf/boot/boot.properties
     -> OpenIDM ready

   • Start OpenIDM (Windows):

     C:\> cd \path\to\openidm
     C:\> startup.bat
     
     "Using OPENIDM_HOME:   \path\to\openidm"
     "Using PROJECT_HOME:   \path\to\openidm"
     "Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m -Dfile.encoding=UTF-8"
     "Using LOGGING_CONFIG: -Djava.util.logging.config.file=\path\to\openidm\conf\logging.properties"
     Using boot properties at \path\to\openidm\conf\boot\boot.properties
     -> OpenIDM ready
     -> 

   At the OSGi console -> prompt, you can enter commands such as help for usage, or ps to view the bundles installed. To see a list of all the OpenIDM core services and their states, enter the following command:

   -> scr list
      Id   State          Name
   [  16] [active       ] org.forgerock.openidm.endpoint
   [  17] [active       ] org.forgerock.openidm.endpoint
   [  37] [active       ] org.forgerock.openidm.endpoint
   [  36] [active       ] org.forgerock.openidm.endpoint
   [  18] [active       ] org.forgerock.openidm.endpoint
   [  38] [active       ] org.forgerock.openidm.endpoint
   [  39] [active       ] org.forgerock.openidm.endpoint
   [  40] [active       ] org.forgerock.openidm.endpoint
   [  32] [active       ] org.forgerock.openidm.endpoint
   [  19] [active       ] org.forgerock.openidm.config.enhanced
   [  49] [active       ] org.forgerock.openidm.selfservice.userupdate
   [   3] [unsatisfied  ] org.forgerock.openidm.datasource.jdbc
   [   7] [active       ] org.forgerock.openidm.http.context
   [  23] [active       ] org.forgerock.openidm.info
   [  41] [active       ] org.forgerock.openidm.info
   [  24] [active       ] org.forgerock.openidm.info
   [  35] [active       ] org.forgerock.openidm.provisioner.openicf.connectorinfoprovider
   [  44] [unsatisfied  ] org.forgerock.openidm.provisioner.salesforce
   [  28] [active       ] org.forgerock.openidm.maintenance.update.log
   [  26] [active       ] org.forgerock.openidm.maintenance.updatemanager
   [   5] [active       ] org.forgerock.openidm.repo.orientdb
   [  34] [active       ] org.forgerock.openidm.openicf.syncfailure
   [   8] [active       ] org.forgerock.openidm.api-servlet
   [   2] [active       ] org.forgerock.openidm.config.enhanced.starter
   [   0] [active       ] org.forgerock.openidm.security
   [  25] [active       ] org.forgerock.openidm.maintenance.update
   [  10] [active       ] org.forgerock.openidm.audit
   [  57] [unsatisfied  ] org.forgerock.openidm.schedule
   [  52] [active       ] org.forgerock.openidm.servletfilter.registrator
   [  11] [active       ] org.forgerock.openidm.auth.config
   [   4] [unsatisfied  ] org.forgerock.openidm.repo.jdbc
   [  55] [active       ] org.forgerock.openidm.workflow
   [  33] [unsatisfied  ] org.forgerock.openidm.provisioner.openicf
   [  15] [active       ] org.forgerock.openidm.managed
   [  22] [active       ] org.forgerock.openidm.health
   [  31] [active       ] org.forgerock.openidm.provisioner
   [  42] [active       ] org.forgerock.openidm.internal
   [  27] [active       ] org.forgerock.openidm.maintenance.update.config
   [  43] [active       ] org.forgerock.openidm.provisioner.salesforce.confighelper
   [  56] [active       ] org.forgerock.openidm.taskscanner
   [  21] [active       ] org.forgerock.openidm.external.rest
   [  50] [active       ] org.forgerock.openidm.ui.context
   [  51] [active       ] org.forgerock.openidm.ui.context
   [  46] [active       ] org.forgerock.openidm.selfservice.kbaservice
   [   9] [active       ] org.forgerock.openidm.router
   [  58] [active       ] org.forgerock.openidm.scheduler
   [  20] [unsatisfied  ] org.forgerock.openidm.external.email
   [  30] [active       ] org.forgerock.openidm.policy
   [   6] [active       ] org.forgerock.openidm.cluster
   [  13] [active       ] org.forgerock.openidm.sync
   [  45] [active       ] org.forgerock.openidm.script
   [  14] [active       ] org.forgerock.openidm.recon
   [  53] [active       ] org.forgerock.openidm.servletfilter
   [  54] [active       ] org.forgerock.openidm.servletfilter
   [  48] [unsatisfied  ] org.forgerock.openidm.selfservice
   [  47] [active       ] org.forgerock.openidm.selfservice.kba
   [  12] [active       ] org.forgerock.openidm.authentication
   [   1] [active       ] org.forgerock.openidm.config.manage
   [  29] [active       ] org.forgerock.openidm.maintenance
   -> 

   A default startup does not include certain configurable services, which will indicate an unsatisfied state until they are included in the configuration. As you work through the sample configurations described later in this guide, you will notice that these services are active.

   Startup errors and messages are logged to the console by default. You can also view these messages in the log files at /path/to/openidm/logs.

2. Alternatively, you can manage the container and services from the Apache Felix Web Console.

   Use these hints to connect to the Apache Felix Web Console:

   • Default URL: https://localhost:8443/system/console

   • Default user name: admin

   • Default password: admin

   Select Main > Components to see OpenIDM core services and their respective states.

1. You can stop OpenIDM Services from the -> prompt in the OSGi console, or through the Apache Felix Web Console. Both of these options stop the Felix container:

   • In the OSGi console, enter the shutdown command at the -> prompt:

     -> shutdown
     ...
     $

   • In the Apache Felix Web Console, select Web Console > System Information to stop the container.

2. On Unix systems, you can stop OpenIDM by using the shutdown.sh script, located in the /path/to/openidm directory:

   $ ./shutdown.sh
   ./shutdown.sh
   Stopping OpenIDM (31391)

You can install OpenIDM to run as a Windows service so that the server starts and stops automatically when Windows starts and stops. You must be logged in as an administrator to install OpenIDM as a Windows service:

1. Unpack the OpenIDM .zip file, as described previously, and change to the install-location\bin directory:

   C:\>cd openidm\bin
   C:\openidm\bin>

2. Run the install-service.bat command, specifying the name the service should run as:

   C:\openidm\bin>install-service.bat openidm
   ForgeRock Launcher Java Service successfully installed as "openidm" service     

3. Use the Windows Service manager to manage the OpenIDM service.

   Running OpenIDM as a Windows Service

   
   
   

4. Change the user account for this service from the default (local system) account to an account with administrative privileges. The local system account has limited permissions and an OpenIDM service that runs with this account will encounter problems during synchronization.

   To change the user account:

   1. Double click the openidm service in the Windows Service manager.

   2. Select the Log On tab.

   3. Select This Account and browse for an Active Directory administrative account.

   4. Enter the password for the administrative account.

      Changing the Service User Account

      
      
      

   5. Click Apply to save the changes.

5. Use the Windows Service Manager to start, stop, or restart the service.

6. To uninstall the OpenIDM service stop the service, then run the following command:

   C:\install-location\openidm\bin>launcher.bat /uninstall openidm
   ...
    Service "openidm" removed successfully
   ...

1. Access the following URL to obtain the JSON representation of all users in the OpenIDM repository:

   $ curl \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids

   When you first install OpenIDM with an empty repository, no users exist.

2. Create a user joe by sending a RESTful POST.

   The following curl commands create the user joe in the repository.

   • Create joe (UNIX):

     $ curl \
      --cacert self-signed.crt \
      --header "Content-Type: application/json" \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request POST \
      --data '{
      "userName":"joe",
      "givenName":"joe",
      "sn":"smith",
      "mail":"joe@example.com",
      "telephoneNumber":"555-123-1234",
      "password":"TestPassw0rd",
      "description":"My first user",
      "_id":"joe"
      }' \
      https://localhost:8443/openidm/managed/user?_action=create
     {
       "_id": "joe",
       "_rev": "1",
       "userName": "joe",
       "givenName": "joe",
       "sn": "smith",
       "mail": "joe@example.com",
       "telephoneNumber": "555-123-1234",
       "description": "My first user",
       "accountStatus": "active",
       "effectiveRoles": [],
       "effectiveAssignments": []
     }

   • Create joe (Windows):

     C:\> curl ^
      --cacert self-signed.crt ^
      --header "Content-Type: application/json" ^
      --header "X-OpenIDM-Username: openidm-admin" ^
      --header "X-OpenIDM-Password: openidm-admin" ^
      --request POST ^
      --data "{
      \"userName\":\"joe\",
      \"givenName\":\"joe\",
      \"sn\":\"smith\",
      \"mail\":\"joe@example.com\",
      \"telephoneNumber\":\"555-123-1234\",
      \"password\":\"TestPassw0rd\",
      \"description\":\"My first user\"
      \"_id\":\"joe\"
      }" ^
      https://localhost:8443/openidm/managed/user?_action=create

3. Fetch the newly created user from the repository with a RESTful GET:

   $  curl \
    --cacert self-signed.crt \
    --header "X-OpenIDM-Username: openidm-admin" \
    --header "X-OpenIDM-Password: openidm-admin" \
    --request GET \
    https://localhost:8443/openidm/managed/user/joe
   {
     "_id": "joe",
     "_rev": "1",
     "userName": "joe",
     "givenName": "joe",
     "sn": "smith",
     "mail": "joe@example.com",
     "telephoneNumber": "555-123-1234",
     "description": "My first user",
     "accountStatus": "active",
     "effectiveRoles": [],
     "effectiveAssignments": []
   }

4. Notice that more attributes are returned for user joe than the attributes you added in the previous step. The additional attributes are added by a script named onCreate-user-set-default-fields.js that is triggered when a new user is created. For more information, see "Managed Object Configuration" in the Integrator's Guide.

   When you create a user some attributes might be required by the policy that is associated with that user. These are listed in the conf/policy.json file.

After you have installed MySQL on the local host and before starting OpenIDM for the first time, set up OpenIDM to use the new repository, as described in the following sections.

This procedure assumes that a password has already been set for the MySQL root user:

1. Download MySQL Connector/J, version 5.1 or later from the MySQL website. Unpack the delivery, and copy the .jar into the openidm/bundle directory:

   $ cp mysql-connector-java-version-bin.jar /path/to/openidm/bundle/

2. Make sure that OpenIDM is stopped:

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

3. Remove the OrientDB configuration file (repo.orientdb.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.orientdb.json

4. Copy the MySQL database connection configuration file (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project's conf directory:

   $ cd /path/to/openidm/
   $ cp db/mysql/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/mysql/conf/repo.jdbc.json my-project/conf/

5. Import the data definition language script for OpenIDM into MySQL:

   $ cd /path/to/mysql
   $ ./bin/mysql -u root -p < /path/to/openidm/db/mysql/scripts/openidm.sql
   Enter password:
   $ 

   This step creates an openidm database for use as the internal repository, and a user openidm with password openidm who has all the required privileges to update the database:

   $ ./bin/mysql -u root -p
   Enter password:
   Welcome to the MySQL monitor.  Commands end with ; or \g.
   Your MySQL connection id is 18
   Server version: 5.5.19 MySQL Community Server (GPL)
   ...
   mysql> use openidm;
   Reading table information for completion of table and column names
   You can turn off this feature to get a quicker startup with -A
   
   Database changed
   mysql> show tables;
   
   +---------------------------+
   | Tables_in_openidm         |
   +---------------------------+
   | auditaccess               |
   | auditactivity             |
   | ...                       |
   | schedulerobjectproperties |
   | schedulerobjects          |
   | security                  |
   | securitykeys              |
   | uinotification            |
   +---------------------------+
   19 rows in set (0.00 sec)

   The table names are similar to those used with OrientDB.

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

   {
       "driverClass" : "com.mysql.jdbc.Driver",
       "jdbcUrl" : "jdbc:mysql://localhost:3306/openidm?allowMultiQueries=true&characterEncoding=utf8",
       "databaseName" : "openidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "bonecp"
       }
   }

These instructions are specific to MS SQL Server 2012 R2 Standard Edition, running on a Windows Server 2012 R2 system. Adapt the instructions for your environment.

After you have installed MS SQL on the local host, install OpenIDM, if you have not already done so, but do not start the OpenIDM instance. Import the data definition and set up OpenIDM to use the MS SQL repository, as described in the following steps:

1. Use SQL Management Studio to import the data definition language script for OpenIDM into MS SQL:

   1. Navigate to SQL Server Management Studio.

   2. On the Connect to Server panel, select Windows Authentication and click Connect.

   3. Select File > Open > File and navigate to the OpenIDM data definition language script (path\to\openidm\db\mssql\scripts\openidm.sql). Click Open to open the file.

   4. Click Execute to run the script.

2. This step creates an openidm database for use as the internal repository, and a user openidm with password Passw0rd who has all the required privileges to update the database. You might need to refresh the view in SQL Server Management Studio to see the openidm database in the Object Explorer.

   Expand Databases > openidm > Tables. You should see the OpenIDM tables in the openidm database, as shown in the following example.

   

   The table names are similar to those used with OrientDB.

3. OpenIDM requires an MS SQL driver that must be created from two separate JAR files. Create the driver as follows:

   1. Download the JDBC Driver 4.1 for SQL Server (sqljdbc_4.1.5605.100_enu.tar.gz) from Microsoft's download site. The precise URL might vary, depending on your location.

      Run the downloaded executable file; it should extract multiple files, include Java archive files, to a dedicated folder.

      Extract the executable Java archive file (sqljdbc41.jar) from the dedicated folder, using 7-zip or an equivalent file management application.

      Copy the Java archive file to openidm\db\mssql\scripts.

   2. Download the bnd Java archive file (bnd-1.50.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      Copy the file to openidm\db\mssql\scripts.

   3. Your openidm\db\mssql\scripts directory should now contain the following files:

      bnd-1.50.0.jar  openidm.sql  sqljdbc4.bnd  sqljdbc4.jar

   4. Bundle the two JAR files together with the following command:

      C:\> cd \path\to\openidm\db\mssql\scripts
      ./> java -jar bnd-1.50.0.jar wrap -properties sqljdbc4.bnd sqljdbc41.jar

      This step creates a single .bar file, named sqljdbc41.bar.

   5. Rename the sqljdbc41.bar file to sqljdbc41-osgi.jar and copy it to the openidm\bundle directory:

      ./> ren sqljdbc41.bar sqljdbc41-osgi.jar
      ./> copy sqljdbc41-osgi.jar \path\to\openidm\bundle

4. Remove the default OrientDB repository configuration file (repo.orientdb.json) from your project's configuration directory. For example:

   C:\> cd \path\to\openidm\my-project\conf\
   .\> del repo.orientdb.json

5. Copy the database connection configuration file for MS SQL (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project's configuration directory. For example:

   C:\> cd \path\to\openidm
   .\> copy db\mssql\conf\datasource.jdbc-default.json my-project\conf\
   .\> copy db\mssql\conf\repo.jdbc.json my-project\conf\

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

   {
       "driverClass" : "com.microsoft.sqlserver.jdbc.SQLServerDriver",
       "jdbcUrl" : "jdbc:sqlserver://localhost:1433;instanceName=default;databaseName=openidm;applicationName=OpenIDM",
       "databaseName" : "openidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "bonecp"
       }
   }

   Specifically, check that the host and port match what you have configured in MS SQL.

Import the OpenIDM schema using the data definition language script (/path/to/openidm/db/oracle/scripts/openidm.sql), as the appropriate schema owner user.

When you have run the script, you should be able to query the internaluser table. The query should return two records (openidm-admin and anonymous). The output here has been formatted for legibility:

SQL> select * from internaluser;

OBJECTID     openidm-admin
-----------------------------------------------------------------------------
REV          0
-----------------------------------------------------------------------------
PWD          openidm-admin
-----------------------------------------------------------------------------
ROLES        [ { "_ref" : "repo/internal/role/openidm-admin" },
               { "_ref" : "repo/internal/role/openidm-authorized" } ]
-----------------------------------------------------------------------------

OBJECTID     anonymous
-----------------------------------------------------------------------------
REV          0
-----------------------------------------------------------------------------
PWD          anonymous
-----------------------------------------------------------------------------
ROLES        [ { "_ref" : "repo/internal/role/openidm-reg" } ]
-----------------------------------------------------------------------------

Before you start OpenIDM, create an Oracle DB driver from two separate jar files and set up the OpenIDM repository configuration for Oracle DB, as follows:

1. Download the Oracle JDBC driver for your Oracle DB version from Oracle Technology Network and place it in the openidm/db/oracle/scripts directory:

   $ ls /path/to/openidm/db/oracle/scripts
   ojdbc7_g.jar    openidm.sql

2. Create a bind file and edit it to match the version information for your JDBC driver.

   You can use the sample bind file located in openidm/db/mssql/scripts. Copy the bind file to the same location as the JDBC driver:

   $ cd /path/to/openidm/db
   $ cp mssql/scripts/sqljdbc4.bnd oracle/scripts
   $ ls oracle/scripts
   ojdbc7_g.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/oracle/scripts
   $ unzip -q -c ojdbc7_g.jar META-INF/MANIFEST.MF
   ...
   Specification-Vendor: Sun Microsystems Inc.
   Specification-Title: JDBC
   Specification-Version: 4.0
   ...

   Edit the bind file to match the JDBC driver version:

   $ more sqljdbc4.bnd
   ...
   version=4.0
   Export-Package: *;version=${version}
   Bundle-Name: Oracle JDBC Driver 4.0 for SQL Server
   Bundle-SymbolicName: Oracle JDBC Driver 4.0 for SQL Server
   Bundle-Version: ${version}

3. Download the bnd Java archive file (bnd-1.50.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

   Place the bnd Java archive file in the same directory as the JDBC driver, and the bind file:

   $ ls /path/to/openidm/db/oracle/scripts
   bnd-1.50.0.jar    ojdbc7_g.jar    openidm.sql    sqljdbc4.bnd

4. 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/oracle/scripts
   $ java -jar bnd-1.50.0.jar wrap -properties sqljdbc4.bnd ojdbc7_g.jar
   Dec 10, 2013 9:53:28 AM java.util.prefs.FileSystemPreferences$1 run
   INFO: Created user preferences directory.
   ojdbc7_g.jar 984 0

   A new .bar file has now been created:

   $ ls
   bnd-1.50.0.jar  ojdbc7_g.bar  ojdbc7_g.jar  openidm.sql  sqljdbc4.bnd

5. Move the .bar file to the openidm/bundle directory and rename it with a .jar extension. The actual name of the file is unimportant:

   $ mv ojdbc7_g.bar /path/to/openidm/bundle/ojdbc7_g-osgi.jar

6. Remove the default OrientDB configuration file (repo.orientdb.json) from your project's configuration directory. For example:

   $ rm /path/to/openidm/my-project/conf/repo.orientdb.json

7. Copy the database connection configuration file for Oracle (datasource.jdbc-default.json) and the database table configuration file (repo.jdbc.json) to your project's configuration directory. For example:

   $ cd /path/to/openidm/
   $ cp db/oracle/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/oracle/conf/repo.jdbc.json my-project/conf/

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

   {
       "driverClass" : "oracle.jdbc.OracleDriver",
       "jdbcUrl" : "jdbc:oracle:thin:@//HOSTNAME:PORT/DEFAULTCATALOG",
       "databaseName" : "openidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "bonecp"
       }
   }

   The "jdbcUrl" corresponds to the URL of the Oracle DB listener, including the service name, based on your configured Local Naming Parameters (tnsnames.ora). It should be whatever is appropriate for your environment.

   The DEFAULTCATALOG should match the user who "owns" the tables. If your schema owner is openidm, the DEFAULTCATALOG should also be openidm. This will cause OpenIDM to generate queries such as "SELECT objectid FROM openidm.internaluser".

   The "username" and "password" corresponds to the credentials of the service user that connects from OpenIDM.

1. OpenIDM includes a script (path/to/openidm/db/postgresql/scripts/createuser.pgsql) that sets up an openidm database and user, with a default password of openidm. The script also grants the appropriate permissions.

   Edit this script if you want to change the password of the openidm user, for example:

   $ more /path/to/openidm/db/postgresql/scripts/createuser.pgsql
   create user openidm with password 'mypassword';
   create database openidm encoding 'utf8' owner openidm;
   grant all privileges on database openidm to openidm;

2. As the postgres user, execute the createuser.pgsql script as follows:

   $ psql -U postgres < /path/to/openidm/db/postgresql/scripts/createuser.pgsql
   CREATE ROLE
   CREATE DATABASE
   GRANT

3. Execute the openidm.pgsql script as the new openidm user that you created in the first step:

   $ psql -U openidm < /path/to/openidm/db/postgresql/scripts/openidm.pgsql
   
   CREATE SCHEMA
   CREATE TABLE
   CREATE TABLE
   CREATE TABLE
   CREATE INDEX
   CREATE INDEX
   ...
   START TRANSACTION
   INSERT 0 1
   INSERT 0 1
   COMMIT
   CREATE INDEX
   CREATE INDEX

   Your database has now been initialized.

4. Remove the OrientDB repository configuration file (repo.orientdb.json) from your project's configuration directory. For example:

   $ rm /path/to/openidm/my-project/conf/repo.orientdb.json

5. Copy the database connection configuration file for PostgreSQL (datasource.jdbc-default.json) and the database table file (repo.jdbc.json) to your project's configuration directory. For example:

   $ cd /path/to/openidm
   $ cp db/postgres/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/postgres/conf/repo.jdbc.json my-project/conf/

6. If you changed the password in step 1 of this procedure, edit the datasource.jdbc-default.json file to set the value for the "password" field to whatever password you set for the openidm user. For example, if you changed the connection password to mypassword, edit the file as follows:

   $ more conf/datasource.jdbc-default.json
   {
       "driverClass" : "org.postgresql.Driver",
       "jdbcUrl" : "jdbc:postgresql://localhost:5432/openidm",
       "databaseName" : "openidm",
       "username" : "openidm",
       "password" : "mypassword",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "bonecp"
       }
   }

7. PostgreSQL is now set up for use as the OpenIDM internal repository.

   Start OpenIDM to check that the setup has been successful. After startup, you should see that repo.jdbc is active, whereas repo.orientdb is unsatisfied:

   -> OpenIDM ready
   scr list
   Id   State          Name
   ...
   [   4] [unsatisfied  ] org.forgerock.openidm.repo.orientdb
   ...
   [   3] [active       ] org.forgerock.openidm.repo.jdbc
   ...
   ->

8. If you are using the default project configuration, run the default_schema_optimization.pgsql script to create the required indexes. This script must be executed by a user with SUPERUSER privileges, so that the extension can be created. By default, this is the postgres user.

   The file includes extensive comments on the indexes that are being created:

   $ psql -U postgres openidm < /path/to/openidm/db/postgresql/scripts/default_schema_optimization.pgsql
   CREATE INDEX
   CREATE INDEX
   CREATE INDEX
   CREATE INDEX
   CREATE INDEX
   CREATE INDEX

Before you start, make sure that OpenIDM is stopped.

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

Set up OpenIDM to use the DB2 repository, as described in the following steps.

1. Create a bundled DB2 JDBC driver, and copy it to the openidm/bundle directory, as follows:

   1. 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

   2. Create a bind file and edit it to match the version information for your JDBC driver.

      You can use the sample bind file located in openidm/db/mssql/scripts. Copy the bind file to the same location as 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 bind 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}

   3. Download the bnd Java archive file (bnd-1.50.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      Place the bnd Java archive file in the same directory as the JDBC driver, and the bind file.

      $ ls /path/to/openidm/db/db2/scripts
      bnd-1.50.0.jar  db2jcc.jar  openidm.sql  sqljdbc4.bnd

   4. 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 bnd-1.50.0.jar wrap -properties sqljdbc4.bnd db2jcc.jar
      Oct 01, 2015 11:50:56 PM java.util.prefs.FileSystemPreferences$1 run
      INFO: Created user preferences directory.
      db2jcc 1149 0

      A new .bar file has now been created.

      $ ls
      bnd-1.50.0.jar  db2jcc.bar  db2jcc.jar  openidm.sql  sqljdbc4.bnd

   5. Move the .bar file to the openidm/bundle directory and rename it with a .jar extension. The actual name of the file is unimportant.

      $ mv db2jcc.bar /path/to/openidm/bundle/db2jcc-osgi.jar

2. Remove the default OrientDB configuration file (repo.orientdb.json) from your project's configuration directory. For example:

   $ rm /path/to/openidm/my-project/conf/repo.orientdb.json

3. 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:

   $ cd /path/to/openidm/
   $ cp db/db2/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/db2/conf/repo.jdbc.json my-project/conf/

4. Edit the connection property in the repository configuration file to match your DB2 environment.

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

   {
       "driverClass" : "com.ibm.db2.jcc.DB2Driver",
       "jdbcUrl" : "jdbc:db2://HOSTNAME:PORT/dopenidm:retrieveMessagesFromServerOnGetMessage=true;",
       "databaseName" : "sopenidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "bonecp"
       }
   }

5. Create a user database for OpenIDM (dopenidm).

   $ db2 create database dopenidm

6. Import the data definition language script for OpenIDM 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.

7. 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
   ------------------------------- --------------- ----- --------------------------
   AUDITACCESS                     SOPENIDM        T     2015-10-01-11.58.04.313685
   AUDITACTIVITY                   SOPENIDM        T     2015-10-01-11.58.03.671342
   AUDITAUTHENTICATION             SOPENIDM        T     2015-10-01-11.58.02.159573
   AUDITCONFIG                     SOPENIDM        T     2015-10-01-11.58.03.307248
   AUDITRECON                      SOPENIDM        T     2015-10-01-11.58.02.526214
   AUDITSYNC                       SOPENIDM        T     2015-10-01-11.58.02.936434
   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
   ...

   The table names are similar to those used with OrientDB.

To perform a migration from OpenIDM 3.1 to OpenIDM 4, follow these steps. For the purposes of this procedure, the path to the existing instance of OpenIDM 3.1 instance is defined as /path/to/openidm-3.1. In contrast, the path to the OpenIDM 4 is defined as /path/to/openidm-4:

1. Download and extract the OpenIDM 4 server.

2. Stop your existing OpenIDM 3.1.0 server, if it is running:

   $ cd /path/to/openidm-3.1
   $ ./shutdown.sh
   Stopping OpenIDM (81491)
       

3. Backup: Save your current deployment. Archive the openidm directory.

4. Boot properties: On the OpenIDM 4 server, edit the conf/boot/boot.properties file to match any customizations that you made on your OpenIDM 3.1 server. Specifically, check the following elements:

   • The HTTP, HTTPS, and mutual authentication ports are specified in the conf/boot/boot.properties file. If you changed the default ports in your OpenIDM 3.1 deployment, make sure that the corresponding ports are specified in this file.

   • Check that the keystore and truststore passwords match the current passwords for the keystore and truststore of your OpenIDM 3.1 deployment.

   Depending on the level of customization you have made in your current deployment, it might be simpler to start with your OpenIDM 3.1 boot.properties file, and copy all new settings from that file to the version associated with OpenIDM 4. However, as a best practice, you should keep all configuration customizations (including new properties and changed settings) in a single location. You can then copy and paste these changes as appropriate.

5. Updating logging.properties

   Recent security fixes prevent Jetty from logging sensitive data, such as passwords. Verify that your conf/logging.properties file includes the following excerpt (and add the excerpt if necessary) to prevent unnecessary data from being logged:

   # Logs the output from Jetty
     # Sets the following Jetty classes to INFO level by default because if logging is set to FINE or higher,
     # sensitive information can be leaked into the logs
     org.eclipse.jetty.server.HttpChannel.level=INFO
     org.eclipse.jetty.server.HttpConnection.level=INFO
     org.eclipse.jetty.server.HttpInput.level=INFO
     org.eclipse.jetty.http.HttpParser.level=INFO
     org.eclipse.jetty.io.ssl.SslConnection.level=INFO

   This configuration logs request data at INFO level, preventing data such as password changes from being logged. In situations where you need to log all data (for example, if you are debugging an issue in a test environment) change the settings here to FINE or FINEST. For example:

   org.eclipse.jetty.server.HttpConnection.level=FINE

6. Security files: Copy the contents of your OpenIDM 3.1 security/ folder to the OpenIDM 4 instance:

   $ cd /path/to/openidm-4
   $ cp -r /path/to/openidm-3.1/security .

   Examine the following excerpt from the boot.properties file. OpenIDM automatically prepends the locations of the keystore.jceks and truststore files with the installation directory.

   ...
   openidm.keystore.type=JCEKS
   openidm.truststore.type=JKS
   openidm.keystore.provider=
   openidm.keystore.location=security/keystore.jceks
   openidm.truststore.location=security/truststore
       

7. Scripts: Migrate any custom scripts or default scripts that you have modified to the scripts directory of your OpenIDM 4 instance. In general, custom and customized scripts should be located in the openidm-3.1/script directory on the OpenIDM 3.1 deployment:

   • For custom scripts, review "OpenIDM Compatibility" in the Release Notes. If you're confident that the scripts will work as intended on OpenIDM 4, then copy these scripts to the new instance. For example:

     $ cd /path/to/openidm-4 
     $ cp /path/to/openidm-3.1/script/my-custom-script.js script/
           

   • If you modified an existing OpenIDM 3.1 script, compare the default versions of the OpenIDM 3.1 and OpenIDM 4 scripts. If you verify that nothing has changed, review what you've customized against "OpenIDM Compatibility" in the Release Notes. If you're confident that your changes will work as intended, then copy the customized scripts to the new openidm-4/script directory. For example:

     $ cd /path/to/openidm-4
     $ cp /path/to/openidm-3.1/script/policy.js script/
           

   • If a default script has changed since the 3.1 release, copy the modified script to the openidm-4/script directory. For example:

     $ cd /path/to/openidm-3.1
     $ cp bin/default/script/linkedView.js script/
           

     Check that your customizations work as expected, then port the changes for OpenIDM 4 to the new script in the openidm-4/script directory.

8. Provisioner files: Modify any customized provisioner configurations in your existing project to point to the connectors that are provided with OpenIDM-4. Specifically, make sure that the "connectorRef" properties reflect the new connectors, where applicable. For example:

   {
        "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
        "bundleVersion": "[1.4.0.0,2.0.0.0)",
        "displayName": "LDAP Connector",
        "connectorName": "org.identityconnectors.ldap.LdapConnector"
   }, 

   Alternatively, copy the connector .jars from your existing installation into the openidm/connectors/ folder of the new installation.

9. Complete the OpenIDM 4 installation, as described in "Installing OpenIDM Services".

10. As there is no automated way to migrate a customized configuration to OpenIDM 4, we recommend the following strategy:

    • Start with the default 3.1 configuration.

    • For each configuration file that you have customized, use a file comparison tool such as the UNIX diff utility to assess the differences between your customized file and the OpenIDM 4 file.

    • Based on the results of the diff, use either your existing file as a base and port the OpenIDM 4 changes to that file, or vice versa. Ultimately, you want to preserve your customizations but ensure that you are up to date with the latest default configuration. All files should end up in the openidm-4/conf directory.

    • Pay particular attention to the conf/repo.jdbc.json file in your existing deployment. Start with a diff between your OpenIDM 3.1 instance and your OpenIDM 4 instance of this file. For a more complete analysis of these differences, see "Changes in Database Schema" in the Release Notes.

      If you have customized this file, make sure that these customizations are ported to the corresponding file updated deployment. For example, if you have defined any new queries, add these queries to the OpenIDM 4 instance of the repo.jdbc.json file.

11. Migrate your internal user data, managed objects, and reconciliation and audit data, if required.

    When you migrate this data, note the following points:

    • Database connection information has been moved from repo.jdbc.json into a separate file, datasource.jdbc-default.json

    • The database audit logging schema has been upgraded significantly for OpenIDM 4:

      • OpenIDM 4 includes new auditauthentication and auditconfig tables.

      • To support additional audit data, OpenIDM 4 includes extensive changes to existing audit tables: auditaccess, auditactivity, auditrecon, and auditsync. These changes include a number of additional fields.

        For more information, see "Using Audit Logs" in the Integrator's Guide.

        If you have used auditing extensively for versions of OpenIDM before OpenIDM 4, read through your repository configuration file, repo.jdbc.json. Compare the six different OpenIDM 4 audit tables with comparable tables in your deployment.

        In many cases, it may be fastest to start new audit tables after a migration to OpenIDM 4.

    • In the link table, OpenIDM 4 includes a new linkQualifier column. When updating your repository, add default as values in that column.

    Your data migration strategy might vary, depending on your repository. You can either migrate your existing 3.1.0 database, or start with a new OpenIDM-4 database and import your existing data.

    Warning

    Before migrating an existing database, review the differences in the repo.jdbc.json files with a DBA. Before running database migration commands, have that DBA review schema scripts in the following directory: /path/to/openidm-4/db/repo/scripts. These scripts typically include a file such as openidm.sql.

    To migrate an existing database:

    • Use the approved schema scripts from the noted OpenIDM-4 db/repo/scripts directory. Apply the changes from that script to your existing database.

      Use the --force option in MySQL (or an equivalent option for your repository type) to create any new tables.

    To start with a new database:

    • Set up a clean repository, using the appropriate schema scripts from the new OpenIDM-4 instance, in the following directory: /path/to/openidm-4/db/repo/scripts).

    • Use a schema comparison tool and adjust the tables in your existing repository to match the schema in the new repository.

    • Export your existing data to the new repository.

12. If you are using the UI, clear your browser cache after the migration. The browser cache contains files from the previous OpenIDM release, that might not be refreshed when you log in to the new UI.

13. Start OpenIDM-4:

    $ cd /path/to/openidm-4
    $ ./startup.sh
        

14. Test that your existing clients and scripts are working as intended.