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 download site. Releases on the ForgeRock BackStage download site 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 directory:

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

4. By default, IDM listens for HTTP and HTTPS connections on ports 8080 and 8443, respectively. To change these port numbers, edit the following settings in your resolver/boot.properties file:

   • openidm.port.http

   • openidm.port.https

   When you deploy IDM in production, you must set openidm.host to the URL of your deployment, in the same resolver/boot.properties file. Otherwise, calls to the /admin endpoint are not properly redirected.

   Deployment URLs will vary, depending on whether you're using a load balancer. While IDM documentation does not specify how you'd configure a load balancer, you'll need to configure IDM in a cluster as described in "Configuring an IDM Instance as Part of a Cluster" in the Integrator's Guide, and specifically in "Deploying Securely Behind a Load Balancer" in the Integrator's Guide.

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

   For more information, see "Selecting a Repository".

To run IDM as a background process, see "Starting, Stopping, and Running 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):

     $ cd /path/to/openidm
     $ ./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 "6.5.2.0"
     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 "6.5.2.0"
     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.ds  enabled
       [  48] [active      ] org.forgerock.openidm.repo.ds
   ...
   -> 

   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)

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 a managed user in the repository, and set the user's ID to jdoe:

   • 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 directory:

     $ 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

To configure a DS instance as an external IDM repository, follow these steps:

1. If you have not yet installed DS, download it from the ForgeRock BackStage download site and extract the zip archive.

2. Install DS with the idm-repo profile, as described in the DS Installation Guide.

   This step configures DS on the localhost, listening on ports 31389 and 34444 so that it does not conflict with the default ports used in the LDAP samples. You can use any hostname and available ports in the setup. If you use a different host and an LDAP port other than 31389, change the primaryLdapServers property in your repo.ds-external.json file accordingly.

3. In your IDM installation, 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

4. Copy the external DS repository configuration file (repo.ds-external.json) to your project's conf directory and rename it repo.ds.json:

   $ cd /path/to/openidm/
   $ cp db/ds/conf/repo.ds-external.json my-project/conf/repo.ds.json

5. If your DS instance is not running on the localhost and listening for LDAP connections on port 31389, adjust the primaryLdapServers property in that file to match your DS setup.

6. Start IDM with the configuration for your project. For example:

   $ cd /path/to/openidm
    $ ./startup.sh -p my-project
    Executing ./startup.sh...
    Using OPENIDM_HOME:   /path/to/openidm
    Using PROJECT_HOME:   /path/to/my-project
    Using OPENIDM_OPTS:   -Xmx1024m -Xms1024m
    Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/my-project/conf/logging.properties
    -> OpenIDM version "6.5.2.0"
    OpenIDM ready

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.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.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. If you have previously set up a MySQL repository for IDM, you must drop the openidm database and users before you continue:

   mysql> drop database openidm;
   Query OK, 21 rows affected (0.63 sec)
   mysql> drop user openidm;
   Query OK, 0 rows affected (0.02 sec)
   mysql> drop user openidm@localhost;
   Query OK, 0 rows affected (0.00 sec)

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

   Note

   If you see errors like Access denied for user 'root'@'localhost', and are deploying on a new installation of Ubuntu 16.04 and above, the UNIX_SOCKET plugin may be installed, which applies Linux root credentials to MySQL. In that case, substitute sudo mysql -u root for mysql -u root -p in the commands in this section.

   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;
   
   +---------------------------+
   | Tables_in_openidm         |
   +---------------------------+
   | clusteredrecontargetids   |
   | clusterobjectproperties   |
   | clusterobjects            |
   | configobjectproperties    |
   | configobjects             |
   | genericobjectproperties   |
   | genericobjects            |
   | ...                       |
   | schedulerobjects          |
   | schedulerobjectproperties |
   | uinotification            |
   | updateobjectproperties    |
   | updateobjects             |
   +---------------------------+
   

   Exit the mysql console.

   mysql> exit
   Bye

7. Create the IDM database user.

   If you are running MySQL 5.7 or higher, run the following script:

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

   If you are running a MySQL version prior to 5.7, run the following script:

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

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

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

10. 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 resolver/boot.properties or your project's conf/system.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/resolver/boot.properties
      -> OpenIDM version "6.5.2.0"
      OpenIDM ready

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

After you have installed Microsoft 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 Microsoft SQL repository, as described in the following steps:

1. Use SQL Management Studio to import the IDM data definition language script into Microsoft 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. Download the Microsoft JDBC Drivers for SQL Server:

   1. Download the JDBC Drivers from Microsoft's download site. IDM requires at least version 7.2 of the driver, which supports OSGi by default.

   2. Extract the driver JAR files using 7-zip or an equivalent file management application.

   3. Copy the JAR file that corresponds to your Java environment to the \path\to\openidm\bundle directory. For example:

      copy mssql-jdbc-7.4.1.jre8.jar \path\to\openidm\bundle

6. Download the JDBC OSGi Service Package JAR and place it in the \path\to\openidm\bundle directory:

   IDM was tested with version 1.0.0 of the service package.

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

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

8. Copy the database connection configuration file for Microsoft 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\

9. Update the connection configuration to reflect your Microsoft 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 resolver/boot.properties or your project's conf/system.properties file, for example:

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

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

     set:OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=1433"

1. As the appropriate schema owner, import the IDM schema using the data definition language script (/path/to/openidm/db/oracle/scripts/openidm.sql).

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

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

   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 are planning to direct audit logs to this repository, run the script that sets up audit tables.

   Use the Oracle SQL Developer Data Modeler to run the following script:

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

4. Set the host and port of the Oracle DB instance, either in the resolver/boot.properties file or through the OPENIDM_OPTS environment variable.

   • If you use the resolver/boot.properties file, set values for the following variables:

     • openidm.repo.host = localhost

     • openidm.repo.port = 1521

   • If you use the OPENIDM_OPTS environment variable, include the JVM memory options when you set the repo host and port. For example:

     export OPENIDM_OPTS="-Xmx1024m -Xms1024m -Dopenidm.repo.host=localhost -Dopenidm.repo.port=1521"

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

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

6. Copy the Oracle DB repository configuration file (repo.jdbc.json) to your project's configuration directory:

   cp /path/to/openidm/db/oracle/conf/repo.jdbc.json my-project/conf/

7. For OracleUCP only

   Edit the repo.jdbc.json file as follows:

   {
       "dbType" : "ORACLE",
       "useDataSource" : "ucp-oracle",
       ...
   }      

8. Copy the connection configuration file to your project's configuration directory and edit the file for your Oracle DB deployment. The connection configuration file depends on the connection pool that you use:

   For Hikari CP

   Copy the following file:

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

   Edit the file to reflect your deployment. The default configuration for a HikariCP connection pool 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
       }
   }

   The jdbcUrl corresponds to the URL of the Oracle DB listener, including the service name, based on your configured Local Naming Parameters tnsnames.ora. Set this parameter according to your database 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.

   For Oracle UCP

   Copy the following file:

   cp /path/to/openidm/db/oracle/conf/datasource.jdbc-ucp-oracle.json my-project/conf/

   Edit the file to reflect your deployment. The default connection configuration for an Oracle UCP connection pool is as follows:

   {
       "databaseName" : "openidm",
       "jsonDataSource" : {
           "class" : "oracle.ucp.jdbc.PoolDataSourceImpl",
           "settings" : {
               "connectionFactoryClassName" : "oracle.jdbc.pool.OracleDataSource",
               "url" : "jdbc:oracle:thin:@&{openidm.repo.host}:&{openidm.repo.port}:SID",
               "user" : "openidm",
               "password" : "openidm",
               "connectionTimeout" : "30000",
               "minPoolSize" : 20,
               "maxPoolSize" : 50
           }
       }
   }

   The url corresponds to the URL of the Oracle DB listener, including the service ID (SID), based on your configured Local Naming Parameters tnsnames.ora. Set this property to the appropriate value for your environment, for example: jdbc:oracle:thin:@localhost:1521:orcl.

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

9. Create an OSGi bundle for the Oracle DB driver, as follows:

   1. Download the JDBC drivers for your Oracle DB version.

      The files that you download depend on your Oracle DB version, and on whether you are using HikariCP or Oracle UCP. Because the version numbers change with minor updates, you must search for the precise corresponding files on oracle.com:

      • Download the ojdbc*.jar file that corresponds to your Oracle DB version.

      • Download bnd-2.4.0.jar. This file lets you create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      • For OracleUCP only

        Download the following files:

        ucp.jar

        ons.jar

      Copy the downloaded files to the /path/to/openidm/db/oracle/scripts directory.

   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 that file to the directory with the JDBC driver, and rename it ojdbc8.bnd:

      cd /path/to/openidm/db
      cp mssql/scripts/sqljdbc4.bnd oracle/scripts/ojdbc8.bnd

      Edit the file for your Oracle version. The resulting file should look similar to the following:

      version=12.2.0.1
      Export-Package: *;version=6.5.2.0
      Bundle-Name: Oracle Database 12.2.0.1 JDBC Driver
      Bundle-SymbolicName: oracle.jdbc.OracleDriver
      Bundle-Version: 6.5.2.0
      Import-Package: *;resolution:=optional

      Note

      Do not include trailing zeros in the version number. For example, for Oracle 12.2.0.1.0, set the version string to version=12.2.0.1.

   3. From the /path/to/openidm/db/oracle/scripts directory, run the following command to create the OSGi bundle, replacing the * with your Oracle DB driver version:

      java -jar bnd-2.4.0.jar wrap --properties ojdbc*.bnd --output ojdbc*-osgi.jar ojdbc*.jar

   4. For OracleUCP only

      Create bnd files for the ucp.jar and ons.jar files. The following examples assume version 12.2.0 Oracle JDBC drivers:

      • ucp.bnd

        version=12.2.0
        Export-Package: oracle.ucp.*;version=${version}
        Bundle-Name: Oracle Universal Connection Pool
        Bundle-SymbolicName: oracle.ucp
        Bundle-Version: ${version}
        Import-Package: *;resolution:=optional
        DynamicImport-Package: *

      • ons.bnd

        version=12.2.0
        Export-Package: *;version=${version}
        Bundle-Name: Oracle ONS
        Bundle-SymbolicName: oracle.ons
        Bundle-Version: ${version}
        Import-Package: *;resolution:=optional

      Save the bnd files in the /path/to/openidm/db/oracle/scripts directory, then run the following commands to create the corresponding OSGi bundles:

      cd /path/to/openidm/db/oracle/scripts
      java -jar bnd-2.4.0.jar wrap --properties ucp.bnd --output ucp-osgi.jar ucp.jar
      java -jar bnd-2.4.0.jar wrap --properties ons.bnd --output ons-osgi.jar ons.jar

      You can ignore any private references warnings that are logged when you build these bundles.

   5. Move all the OSGi bundle files to the openidm/bundle directory.

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

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 plan 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.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.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 resolver/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/resolver/boot.properties
     -> OpenIDM version "6.5.2.0"
     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.ds 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/resolver/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.ds  enabled
    ...

11. Set up indexes to tune the PostgreSQL repository according to your specific deployment.

    Important

    No indexes are set by default. If you do not tune the repository correctly by creating the required indexes, the performance of your service can be severely impacted. For example, setting too many indexes can have an adverse effect on performance during managed object creation. Conversely, not indexing fields that are searched will severely impact search performance.

    IDM includes a /path/to/openidm/db/postgresql/scripts/default_schema_optimization.pgsql script that sets up a number of indexes. This script includes extensive comments on the indexes that are being created. Review the script before you run it to ensure that all the indexes are suitable for your deployment.

    When you have refined the script for your deployment, execute the script as a user with superuser privileges, so that the required extensions can be created. By default, this is the postgres user:

    $ 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 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}

   3. Download the bnd JAR file (bnd-2.4.0.jar) that lets you 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:

      $ ls /path/to/openidm/db/db2/scripts
      bnd-2.4.0.jar  db2jcc.jar

   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-osgi.jar  db2jcc.jar

   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.ds.json) from your project's conf/ directory. For example:

   $ cd /path/to/openidm/my-project/conf/
   $ rm repo.ds.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 resolver/boot.properties or your project's conf/system.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/resolver/boot.properties
     -> OpenIDM version "6.5.2.0"
     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. Update your Java environment.

   IDM requires a supported Java environment, as described in "Preparing the Java Environment" in the Release Notes.

   If your server uses an older version, install a newer Java version before you update and follow the instructions in "Java Prerequisites".

2. Download the new software.

   Download and extract IDM-6.5.2.0.zip from the ForgeRock BackStage download site.

3. Back up your existing deployment by archiving the openidm directory and the contents of your repository.

4. If you have encrypted or obfuscated any properties in configuration files, decrypt them into their plain text values before you start the update. When you have completed the update, you can encrypt or obfuscate the values again.

5. Save your audit data. If you want to preserve a record of the audit logs collected while IDM 6.0 was running, save these log files manually before you start the update process. You can find the log files in the /path/to/openidm/audit/ directory. For more information on these files, see "Audit Event Topics" in the Integrator's Guide.

   Tip

   File rotation tip: When you delete files in the /path/to/openidm/audit/ directory, IDM creates new files as needed in the same directory.

1. Delete the existing openidm/ui/admin/extension subdirectory.

2. Copy the default UI files from the openidm/ui/admin/default subdirectory with the following command:

   $ cd /path/to/openidm/ui
   $ cp -r admin/default/. admin/extension

3. Review any custom UI files from your IDM 6.0 deployment and compare them against the IDM 6.5.2.0 version of these files.

4. Apply custom changes to each new IDM 6.5 UI file in the openidm/ui/admin/extension and subdirectory.

1. Download IDM-6.5.2.0.zip from ForgeRock's BackStage site.

2. Copy IDM-6.5.2.0.zip to /path/to/openidm/bin/update.

3. Back up your 6.5 deployment. Save any customized *.json configuration files, located in your project's /conf directory. Save your custom directories.

4. If you have a read-only deployment, mount the directory in read-write mode before starting the update.

5. If you integrated IDM with AM, disable the authentication modules that you used.

6. If you have a custom resolver/boot.properties file in your IDM 6.5 deployment, you will need to copy the file to your 6.5.2.0 deployment. For example, if you have an IDM 6.5 deployment, extract IDM-6.5.2.0.zip to a temporary directory. Then, copy the custom IDM 6.5 resolver/boot.properties file to your 6.5.2.0 resolver directory.

   If you have not customized the default resolver/boot.properties file in your deployment, you can simply overwrite it with version 6.5.2.0 of this file.

7. Start IDM. IDM must be running when you launch an update.

   Note

   You must use the CLI to update your system. As of IDM 6.5, the facility to update servers through the Admin UI has been removed.

8. Disable and re-enable connections to AM.

1. Go to your IDM installation:

   $ cd /path/to/openidm

2. Run the cli.sh command with the --skipRepoUpdatePreview option. There are no repository updates during a patch release:

   $ ./cli.sh update \
     --acceptLicense \
     --user openidm-admin:openidm-admin \
     --url http://localhost:8080/openidm \
     --skipRepoUpdatePreview \
     IDM-6.5.2.0.zip

3. The update process continues and completes with "Scheduler has been resumed."

   Executing ./cli.sh...
   Starting shell in /Users/namespace/Downloads/openidm
   License was accepted via command line argument.
   Repository update preview was skipped.
   Pausing the Scheduler
   Scheduler has been paused.
   Waiting for running jobs to finish.
   All running jobs have finished.
   Entering into maintenance mode...
   Now in maintenance mode.
   Installing the update archive IDM-6.5.2.0.zip
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   Update procedure is still processing...
   The update process is complete.
   Exiting maintenance mode...
   No longer in maintenance mode.
   Resuming the job scheduler.
   Scheduler has been resumed..

4. After update, check if you have multiple versions of the bundle/openidm-repo-opendj-<version> files, for example, bundle/openidm-repo-opendj-6.5.0.x.jar. Manually remove the oldest version, which should be the file generated from the release before the 6.5.2.0 update.

5. Manually update the conf/ui-themeconfig.json. Change the Bootstrap version to css/bootstrap-3.4.1-custom.css from the previous 3.3.7 version.

   The update does not touch this file, to avoid overwriting possible customization of the UI theme.

6. If you have a custom Jetty configuration, see the Release Notes for an important change in functionality.

7. If you have customized your version 6 deployment, you might find files with the following extensions: .old and .new.

   On Linux/UNIX systems, you can locate these files with the following commands:

   $ cd /path/to/openidm
   $ find . -type f -name "*.old*"
   $ find . -type f -name "*.new*"

   Files with the .old-unix_time extension are saved from your configuration before starting this update process. Files with the .new-unix_time extension are files from the IDM 6 configuration that have not been included in your updated installation.

   For example, if you find a system.properties.new-unix_time file in your project directory, IDM is still using the version of this file before the update (which would still be named system.properties).

   To make sure that you have a completely upgraded configuration, analyze the new features in any files with the .new-unix_time extension, and copy those changes into your existing configuration. If you have similar files with multiple .new-unix_time extensions, use the file with the latest unix_time.

8. Restart your server.

   Your update has successfully completed.