PingIDM 7.5.0

Install and run IDM

Use the procedures in this section to install, start, run, and stop IDM.

Install IDM

Follow these steps to install IDM:

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

    java -version
OpenJDK version "17.0.3" 2022-05-02
OpenJDK Runtime Environment Temurin-17.0.3+8 (build 17.0.3+8)
OpenJDK 64-Bit Server VM Temurin-17.0.3+8 (build 17.0.3+8, mixed mode)

    For a description of the Java requirements, refer to Before you install.

  2. Download IDM from Backstage. Releases on Backstage 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-7.5.0.zip
Archive:  IDM-7.5.0.zip
  inflating: openidm/.checksums.csv
   creating: openidm/bundle/
 extracting: openidm/bundle/openidm-audit-7.5.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 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 IDM cluster configuration, and specifically in Deploy Securely Behind a Load Balancer.

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

    For more information, refer to Select a repository.

Start IDM

To adjust the JVM heap size before starting IDM, refer to Change the JVM heap size.

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:

    • Bash

    • PowerShell

    /path/to/openidm/startup.sh
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/openidm
Using OPENIDM_OPTS:   -Xmx2048m -Xms2048m
Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
-> OpenIDM version "7.5.0"
OpenIDM ready
    \path\to\openidm\startup.bat
"Using OPENIDM_HOME:   \path\to\openidm"
"Using PROJECT_HOME:   \path\to\openidm"
"Using OPENIDM_OPTS:   -Xmx2048m -Xms2048m -Dfile.encoding=UTF-8"
"Using LOGGING_CONFIG: -Djava.util.logging.config.file=\path\to\openidm\conf\logging.properties"
-> OpenIDM version "7.5.0"
OpenIDM ready

    At the OSGi console -> prompt, you can enter commands such as help for usage, or ps to view the bundles installed.

    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:

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

Run IDM as a background process

You can also start IDM as a background process on UNIX and Linux systems. Follow these steps, preferably before you start IDM for the first time:

  1. If you have already started the server, shut it down and remove the Felix cache files under openidm/felix-cache/ :

    shutdown
...
rm -rf felix-cache/*

  2. Start the server in the background. The nohup survives a logout, and the 2>&1& redirects standard output and standard error to the noted console.out file:

    nohup ./startup.sh > logs/console.out 2>&1&
[1] 2343

To stop the server running as a background process, use the shutdown.sh script:

./shutdown.sh
Stopping OpenIDM (2343)

Although installations on macOS systems are not supported in production, you might want to run IDM on macOS in a demo or test environment. To run IDM in the background on a macOS system, take the following additional steps:

  • Remove the org.apache.felix.shell.tui-*.jar bundle from the openidm/bundle directory.

  • Disable ConsoleHandler logging.

Stop IDM

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.

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

  3. On Unix systems, you can stop IDM by using the shutdown.sh script:

    /path/to/openidm/shutdown.sh
Stopping OpenIDM (31391)

Uninstall IDM

  1. Stop the server if it is running, as described in Stop IDM.

  2. Remove the directory where you installed the software:

    rm -rf /path/to/openidm

  3. If you use a JDBC database for the repository, drop the openidm database.

Start IDM in debug mode

To debug custom libraries, start the server with the Java Platform Debugger Architecture (JPDA):

  1. Start IDM with the jpda option:

    /path/to/openidm/startup.sh jpda
Executing ./startup.sh...
Using OPENIDM_HOME:   /path/to/openidm
Using OPENIDM_OPTS:   -Xmx2048m -Xms2048m -Djava.compiler=NONE -Xnoagent -Xdebug
 -Xrunjdwp:transport=dt_socket,address=5005,server=y,suspend=n
Using LOGGING_CONFIG:
   -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
Listening for transport dt_socket at address: 5005
Using boot properties at /path/to/openidm/resolver/boot.properties
-> OpenIDM version "7.5.0" (revision: xxxx)
OpenIDM ready

    The relevant JPDA options are listed in the startup script (startup.sh).

  2. In your IDE, attach a Java debugger to the JVM via socket on port 5005.

This interface is internal and subject to change. If you depend on this interface, contact ForgeRock support.

Change the JVM heap size

Changing the JVM heap size can improve performance and reduce the time it takes to run reconciliations.

You can set the JVM heap size via the OPENIDM_OPTS environment variable. If OPENIDM_OPTS is undefined, the JVM maximum heap size defaults to 2GB. For example, to set the minimum and maximum heap sizes to 4GB, enter the following before starting IDM:

  • Unix/Linux

  • Windows

cd /path/to/openidm/
export OPENIDM_OPTS="-Xms4096m -Xmx4096m"
./startup.sh
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/openidm
Using OPENIDM_OPTS:   -Xms4096m -Xmx4096m
...
OpenIDM ready
cd \path\to\openidm
set OPENIDM_OPTS=-Xms4096m -Xmx4096m
startup.bat
"Using OPENIDM_HOME:   \path\to\openidm"
"Using PROJECT_HOME:   \path\to\openidm"
"Using OPENIDM_OPTS:   -Xms4096m -Xmx4096m -Dfile.encoding=UTF-8"
...
OpenIDM ready

You can also edit the OPENIDM_OPTS values in startup.sh or startup.bat.

For more information about tuning and load testing, refer to Load testing