Follow these steps to install IDM:

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

   $ java -version
   java version "1.8.0_121"
   Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
   Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)

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

2. Download IDM from the ForgeRock BackStage site. The ForgeRock BackStage site provides access to ForgeRock releases. These releases are thoroughly validated for ForgeRock customers who run the software in production deployments, and for those who want to try or test a given release.

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

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

4. By default, IDM 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 "Host and Port Information" in the Integrator's Guide.

   The hostname associated with IDM by default is localhost. To change the default hostname, edit the openidm.host property in your project's conf/boot/boot.properties file.

5. Before running IDM in production, replace the default DS repository with a supported JDBC repository.

   For more information, see "Selecting a Repository".

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

Follow these steps to run IDM interactively:

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

   • Start IDM (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
     -> OpenIDM version "5.5.1.3"
     OpenIDM ready

   • Start IDM (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"
     -> OpenIDM version "5.5.1.3"
     OpenIDM ready
     -> 

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

   -> scr list
   BundleId Component Name Default State
       Component Id State      PIDs (Factory PID)
   [   5]   org.forgerock.openidm.config.enhanced.starter  enabled
       [   1] [active      ] org.forgerock.openidm.config.enhanced.starter
   [   5]   org.forgerock.openidm.config.manage  enabled
       [   0] [active      ] org.forgerock.openidm.config.manage
   [  10]   org.forgerock.openidm.datasource.jdbc  enabled
   [  10]   org.forgerock.openidm.repo.jdbc  enabled
   [  11]   org.forgerock.openidm.repo.opendj  enabled
       [  48] [active      ] org.forgerock.openidm.repo.opendj
   ...
   -> 

   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 core services and their respective states.

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

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

   -> shutdown
   ...
   $

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

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

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

You can install IDM 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 a Windows service:

1. Unpack the IDM-5.5.1.3.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 that 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 IDM service.

   Running 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 IDM 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

      
      
      

      Click Apply to save the changes.

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

6. To uninstall the IDM 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 IDM 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 IDM 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 \
      --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"
      }' \
      http://localhost:8080/openidm/managed/user?_action=create
     {
       "_id": "joe",
       "_rev": "00000000c03fd7aa",
       "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 ^
      --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\"
      }" ^
      http://localhost:8080/openidm/managed/user?_action=create

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

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

Set up a new project as follows:

1. Create a directory for your new project:

   $ mkdir /path/to/my-project

   Note that the automated update process does not work for projects that are subdirectories of the default project. You should therefore create your new project directory somewhere outside of /path/to/openidm/.

2. Set up a minimal configuration:

   • If your project will be similar to any of the sample configurations (described in the Samples Guide) copy the contents of the sample to your new project.

     For example:

     $ cp -r /path/to/openidm/samples/sync-with-ldap/* /path/to/my-project/

     You can then customize the sample configuration according to your requirements.

   • If you do not want to start with one of the sample configurations, copy the conf/ and script/ directories from the default project to your new project location:

     $ cd /path/to/openidm
     $ cp -pr conf /path/to/my-project/
     $ cp -pr script /path/to/my-project/

     You can then customize the basic configuration according to your requirements.

3. Start your new project as follows:

   $ cd /path/to/openidm
   $ ./startup.sh -p /path/to/my-project

After you have installed MySQL on the local host and before starting IDM for the first time, configure the server 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 IDM is stopped:

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

3. Remove the default DS repository configuration file (repo.opendj.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.opendj.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 IDM data definition language script into MySQL:

   $ cd /path/to/mysql
   $ 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:

   $ 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;
   
   mysql> show tables;
   +---------------------------+
   | Tables_in_openidm         |
   +---------------------------+
   | clusteredrecontargetids   |
   | clusterobjectproperties   |
   | clusterobjects            |
   | configobjectproperties    |
   | configobjects             |
   | genericobjectproperties   |
   | genericobjects            |
   | ...                       |
   | schedulerobjects          |
   | securitykeys              |
   | uinotification            |
   | updateobjectproperties    |
   | updateobjects             |
   +---------------------------+
   21 rows in set (0.00 sec)
   
   

   Exit the mysql console.

   mysql> exit
   Bye

6. Run the three scripts that set up the tables required by the Activiti workflow engine.

   If you are running MySQL 5.6.4 or higher, run the following scripts:

   $ cd /path/to/mysql
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.engine.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.history.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.identity.sql
   Enter password: 
      

   If you are running a MySQL version prior to 5.6.4, run the following scripts:

   $ cd /path/to/mysql
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql55.create.engine.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql55.create.history.sql
   Enter password: 
   $ mysql -D openidm -u root -p < /path/to/openidm/db/mysql/scripts/activiti.mysql.create.identity.sql
   Enter password: 
      

7. If you are planning to direct audit logs to this repository, run the script that sets up the audit tables:

   $ mysql -D openidm -u root -p < openidm/db/mysql/scripts/audit.sql
   Enter password: 

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

   {
       "driverClass" : "com.mysql.jdbc.Driver",
       "jdbcUrl" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/openidm?allowMultiQueries=true&characterEncoding=utf8",
       "databaseName" : "openidm",
       "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 the values in your project's conf/system.properties or conf/boot/boot.properties file, for example:

     openidm.repo.host = localhost
     openidm.repo.port = 3306

   • 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=3306"
     $ ./startup.sh -p /path/to/openidm/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=3306
     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 version "5.5.1.3"
     OpenIDM ready

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 IDM, if you have not already done so, but do not start the instance. Import the data definition and configure IDM to use the MS SQL repository, as described in the following steps:

1. Use SQL Management Studio to import the IDM data definition language script 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 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 openidm 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 IDM tables in the openidm database, as shown in the following example.

   

3. Execute the three scripts that set up the tables required by the Activiti workflow engine:

   You can use the sqlcmd command to execute the scripts, for example:

   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
       -i C:\path\to\openidm\db\mssql\scripts\activiti.mssql.create.engine.sql
   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
       -i C:\path\to\openidm\db\mssql\scripts\activiti.mssql.create.history.sql
   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
       -i C:\path\to\openidm\db\mssql\scripts\activiti.mssql.create.identity.sql

   Note

   When you run the activiti.mssql.create.engine.sql script, you might see the following warning in the log:

   Warning! The maximum key length is 900 bytes. The index 'ACT_UNIQ_PROCDEF' has maximum
   length of 1024 bytes. For some combination of large values, the insert/update operation will fail.

   It is very unlikely that the key length will be an issue in your deployment, and you can safely ignore this warning.

4. If you are going to direct audit logs to this repository, run the script that sets up the audit tables:

   PS C:\Users\Administrator> sqlcmd -S localhost -d openidm ^
    -i C:\path\to\openidm\db\mssql\scripts\audit.sql

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

   1. Download the JDBC Driver for SQL Server from Microsoft's download site. IDM requires at least version 4.2 of the driver (sqljdbc_4.2.8112.100_enu.tar.gz). The precise download URL might vary, depending on your location.

      Extract the JAR file (sqljdbc42.jar), using 7-zip or an equivalent file management application and copy the file to the openidm\db\mssql\scripts directory.

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

      Copy this JAR file to openidm\db\mssql\scripts.

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

      bnd-2.4.0.jar  sqljdbc4.bnd  sqljdbc42.jar

   4. Create an OSGi bundle from the driver JAR with the following command:

      C:\> cd \path\to\openidm\db\mssql\scripts
      ./> java -jar bnd-2.4.0.jar wrap --properties sqljdbc4.bnd --output sqljdbc42-osgi.jar sqljdbc42.jar

      This step creates the OSGi bundle named sqljdbc42-osgi.jar.

   5. Copy the sqljdbc42-osgi.jar file to the openidm\bundle directory:

      ./> copy sqljdbc42-osgi.jar \path\to\openidm\bundle

6. Remove the default DS repository configuration file (repo.opendj.json) from your project's conf/ directory. For example:

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

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

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

   {
       "driverClass" : "com.microsoft.sqlserver.jdbc.SQLServerDriver",
       "jdbcUrl" : "jdbc:sqlserver://&{openidm.repo.host}:&{openidm.repo.port};instanceName=default;databaseName=openidm;applicationName=OpenIDM",
       "databaseName" : "openidm",
       "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 the values in your project's conf/system.properties or conf/boot/boot.properties file, for example:

     openidm.repo.host = localhost
     openidm.repo.port = 1433

   • 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=1433"
     $ cd /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=1433
     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 version "5.5.1.3"
     OpenIDM ready

1. Import the IDM 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" } ]
   -----------------------------------------------------------------------------

2. Run the three scripts that set up the tables required by the Activiti workflow engine.

   You can use the Oracle SQL Developer Data Modeler to run the scripts, as described in the corresponding Oracle documentation.

   You must run the following scripts:

   /path/to/openidm/db/oracle/scripts/activiti.oracle.create.engine.sql
   /path/to/openidm/db/oracle/scripts/activiti.oracle.create.history.sql
   /path/to/openidm/db/oracle/scripts/activiti.oracle.create.identity.sql

3. If you plan to direct audit logs to this repository, run the script that sets up the audit tables:

   You can use the Oracle SQL Developer Data Modeler to run the scripts, as described in the previous step.

   You must run the following script:

   /path/to/openidm/db/oracle/scripts/audit.sql

4. Create an Oracle DB driver from two separate jar files and set up the 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 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 the bnd 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 bnd 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 JAR file (bnd-2.4.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      Place the bnd JAR file in the same directory as the JDBC driver, and the bnd file:

      $ ls /path/to/openidm/db/oracle/scripts
      bnd-2.4.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-2.4.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-2.4.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. It does not matter what you name the file:

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

5. Remove the default DS repository configuration file (repo.opendj.json) from your project's conf/ directory. For example:

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

6. 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/

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

   {
       "driverClass" : "oracle.jdbc.OracleDriver",
       "jdbcUrl" : "jdbc:oracle:thin:@//&{openidm.repo.host}:&{openidm.repo.port}/DEFAULTCATALOG",
       "databaseName" : "openidm",
       "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 the values in your project's conf/system.properties or conf/boot/boot.properties file, for example:

     openidm.repo.host = localhost
     openidm.repo.port = 1525

   • 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=1525"
     $ cd /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=1525
     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 version "5.5.1.3"
     OpenIDM ready

   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 refers to the SID (system identifier), for example, orcl.

   The username and password correspond to the credentials of the service user that connects from IDM.

1. The path/to/openidm/db/postgresql/scripts/createuser.pgsql script 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. Edit the Postgres client authentication configuration file, pg_hba.conf. Add the following entries for the following users: postgres and openidm:

   local   all   openidm      trust
   local   all   postgres      trust

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

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

5. Run the three scripts that set up the tables required by the Activiti workflow engine:

   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/activiti.postgres.create.engine.sql
   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/activiti.postgres.create.history.sql
   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/activiti.postgres.create.identity.sql

6. If you are going to direct audit logs to this repository, run the script that sets up the audit tables:

   $ psql -d openidm -U openidm < /path/to/openidm/db/postgresql/scripts/audit.pgsql

7. Remove the default DS repository configuration file (repo.opendj.json) from your project's conf/ directory. For example:

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

8. 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/postgresql/conf/datasource.jdbc-default.json my-project/conf/
   $ cp db/postgresql/conf/repo.jdbc.json my-project/conf/

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

   {
       "driverClass" : "org.postgresql.Driver",
       "jdbcUrl" : "jdbc:postgresql://&{openidm.repo.host}:&{openidm.repo.port}/openidm",
       "databaseName" : "openidm",
       "username" : "openidm",
       "password" : "openidm",
       "connectionTimeout" : 30000,
       "connectionPool" : {
           "type" : "hikari",
           "minimumIdle" : 20,
           "maximumPoolSize" : 50
       }
   }

   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.

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

   • Set the values in your project's conf/boot/boot.properties file:

     openidm.repo.host = localhost
     openidm.repo.port = 5432

   • 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=5432"
     $ cd /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=5432
     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 version "5.5.1.3"
     OpenIDM ready

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

    Start IDM with the configuration for your project. Monitor the console for the success of your setup. After startup, run a scr list command. In the output, you should see that repo.jdbc is active, whereas repo.opendj is enabled but not active:

    $ cd /path/to/openidm
    $ ./startup.sh -p my-project
    Using OPENIDM_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
    -> scr list
    BundleId Component Name Default State
        Component Id State      PIDs (Factory PID)
     [   5]   org.forgerock.openidm.config.enhanced.starter  enabled
        [   1] [active      ] org.forgerock.openidm.config.enhanced.starter
     [   5]   org.forgerock.openidm.config.manage  enabled
        [   0] [active      ] org.forgerock.openidm.config.manage
     [  10]   org.forgerock.openidm.datasource.jdbc  enabled
     [  10]   org.forgerock.openidm.repo.jdbc  enabled
        [  48] [active      ] org.forgerock.openidm.repo.jdbc
     [  11]   org.forgerock.openidm.repo.opendj  enabled
    ...

11. 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 the server is stopped.

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

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

1. Create an OSGi bundle for the DB2 JDBC driver, 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 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 the bnd 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 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}

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

      Place the bnd JAR file in the same directory as the JDBC driver, and the bnd file.

      $ ls /path/to/openidm/db/db2/scripts
      bnd-2.4.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-2.4.0.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
      bnd-2.4.0.jar  db2jcc.bar  db2jcc.jar  openidm.sql  sqljdbc4.bnd

   5. Move the OSGi bundle fle to the openidm/bundle directory:

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

2. Remove the default DS repository configuration file (repo.opendj.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.opendj.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. 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 the values in your project's conf/system.properties or conf/boot/boot.properties file, for example:

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

   • 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"
     $ cd /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/conf/boot/boot.properties
     -> OpenIDM version "5.5.1.3"
     OpenIDM ready

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

   $ db2 create database dopenidm

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

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

8. Connect to the openidm database, then run the three scripts that set up the tables required by the Activiti workflow engine:

   $ db2 connect to dopenidm
   $ db2 -i -tf /path/to/openidm/db/db2/scripts/activiti.db2.create.engine.sql
   $ db2 -i -tf /path/to/openidm/db/db2/scripts/activiti.db2.create.history.sql
   $ db2 -i -tf /path/to/openidm/db/db2/scripts/activiti.db2.create.identity.sql

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

1. Download the patch release from the ForgeRock BackStage site. For example: download IDM-<patch-version>-patch.zip.

   Note

   Patch releases are cumulative. There is no need to install a previous patch release. For example, you only need to download and install IDM-<patch-version>-patch.zip.

2. Unzip the patch file to a temporary folder and compare the contents to /path/to/openidm-<patch-version>. If you are comfortable with the changes, continue with the process.

3. Make sure that your server instance is started.

4. Copy the update binary to the /path/to/openidm/bin/update directory:

   $ cp IDM-<patch-version>-patch.zip path/to/openidm/bin/update

5. Run the update process, using the CLI or the Admin UI. The following command runs the process over the command line. See "Updating From the Admin UI" for a similar process using the Admin UI:

   $ cd /path/to/openidm
   
   $ ./cli.sh update \
   --skipRepoUpdatePreview \
   --acceptLicense \
   --user openidm-admin:openidm-admin \
   --url http://localhost:8080/openidm \
   IDM-<patch-version>-patch.zip

6. When the update is complete, restart IDM.

If you are on a Windows-based system, you must apply the patch release manually.

This procedure outlines how to apply the patch release IDM-<patch-version>-patch.zip to an existing IDM <patch-version> instance located at \path\to\idm-<patch-version>.

1. Download the patch release from the ForgeRock BackStage site. For example: download IDM-<patch-version>-patch.zip.

2. Unzip the patch file to a temporary folder and compare the contents to \path\to\idm-<patch-version>. If you are comfortable with the changes, continue with the process.

3. Shut down the IDM <patch-version> instance.

4. Back up your current IDM <patch-version> instance located at \path\to\idm-<patch-version>.

5. Unzip the IDM-<patch-version>-patch.zip to \path\to\idm-<patch-version>.

   cd \path\to\idm-<patch-version>
   unzip IDM-<patch-version>-patch.zip

6. Inspect the contents of the \path\to\idm-<patch-version>\bundle* directory. For example, remove any duplicates that were applied in the patch. Find each instance of *-IDM-<patch-version>.jar and remove the corresponding IDM-<patch-version>.jar.

   For example, for patch version IDM 5.5.0.3, remove the following affected jar files:

   openidm-authnfilter-5.5.0.3.jar

   openidm-provisioner-openicf-5.5.0.3.jar

   openidm-security-jetty-5.5.0.3.jar

   openidm-ui-admin-5.5.0.3.jar

   script-javascript-5.5.0.3.jar

   openidm-core-5.5.0.3.jar

   openidm-external-rest-5.5.0.3.jar

   openidm-security-5.5.0.3.jar

   openidm-system-5.5.0.3.jar

   script-groovy-5.5.0.3.jar

   openidm-quartz-fragment-5.5.0.3.jar

   openidm-servlet-registrator-5.5.0.3.jar

   script-common-5.5.0.3.jar

7. Remove the felix-cache directory.

   rm -rf felix-cache

8. Restart IDM.