Requirements

ForgeRock supports customers deploying DS in Docker containers and Kubernetes platforms, as well as bare metal and VM deployments, provided you follow the hardware and software requirements specified here.

Other versions and alternative environments might work as well. When opening a support ticket for an issue, however, make sure you can also reproduce the problem on a combination covered here.

Downloads

The ForgeRock BackStage download site provides access to ForgeRock releases.

File Description

DS-7.1.0.zip

Cross-platform distribution of the server software.

Pure Java, high-performance server that can be configured as:

  • An LDAPv3 directory server with the additional capability to serve directory data to REST applications over HTTP.

  • An LDAPv3 directory proxy server providing a single point of access to underlying directory servers.

  • A replication server handling replication traffic with directory servers and with other replication servers, receiving and sending changes to directory data.

Server distributions include command-line tools for installing, configuring, and managing servers. The tools make it possible to script all operations.

By default, this file unpacks into an opendj/ directory.

DS-7.1.0.msi

Microsoft Windows native installer for the server software.

By default, this installs files into a C:\Program Files (x86)\OpenDJ\ directory.

DS_7.1.0-1_all.deb

Server software native packages for Debian and related Linux distributions.

By default, this installs files into an /opt/opendj/ directory.

DS-7.1.0-1.noarch.rpm

Server software native packages for Red Hat and related Linux distributions.

By default, this installs files into an /opt/opendj/ directory.

DS-dsml-servlet-7.1.0.war

Cross-platform DSML gateway web archive.

DS-rest2ldap-servlet-7.1.0.war

Cross-platform REST to LDAP gateway web archive.

Hardware

Thanks to the underlying Java platform, Directory Services software runs well on a variety of processor architectures. Many directory service deployments meet their service-level agreements without the very latest or very fastest hardware.

Memory

When installing a directory server for evaluation, you need 256 MB memory (32-bit) or 1 GB memory (64-bit) available.

For installation in production:

  • As a rule of thumb, the RAM available for the server should be at least 1.5 to 2 times the total size of the database files on disk, or at minimum 2 GB.

  • Provide four times the disk space needed for initial production data in LDIF format.

    A replicated directory server stores data, indexes for the data, operational attribute data, and historical information for replication. The server configuration trades disk space for performance and resilience, compacting and purging data for good performance, and for protection against temporary outages. In addition, leave space for growth in database size as client applications modify and add entries over time.

  • For a more accurate estimate of the disk space needed, import a known fraction of the initial LDIF with the server configured for production. Run tests to estimate change and growth in directory data, and extrapolate from the actual space occupied in testing to estimate the disk space required in production.

  • Directory servers almost always benefit from caching all directory database files in system memory.

    Reading from and writing to memory is much faster than reading from and writing to disk storage.

  • For large directories with millions of user directory entries, there might not be room to install enough memory to cache everything.

    To improve performance in such cases, use quality solid state drives either for all directory data, or as an intermediate cache between memory and disk storage.

Disk Space

To evaluate DS software, make sure you have 10 GB free disk space for the software and for sample data.

The more data you have, the more disk space you need. Before deploying production systems, make sure you have enough space. For details, see Plan to Scale.

CPU Architectures

Processor architectures that provide fast single thread execution tend to help Directory Services software deliver the lowest response times. For top-end performance in terms of sub-millisecond response times and of throughput ranging from tens of thousands to hundreds of thousands of operations per second, the latest x86/x64 architecture chips tend to perform better than others.

When deploying DS servers with replication enabled, allow at minimum two CPU cores per server. Allow more CPU cores per server, especially in high-volume deployments or when using CPU-intensive features such as encryption. Single CPU systems seriously limit server performance.

Chip multi-threading (CMT) processors can work well for directory servers providing pure search throughput, though response times are higher. However, CMT processors are slow to absorb hundreds or thousands of write operations per second. Their slower threads get blocked waiting on resources, and thus are not optimal for deployments with high write throughput requirements.

Network

On systems with fast processors and enough memory to cache directory data completely, the network can become a bottleneck. Even if a single 1 Gb Ethernet interface offers plenty of bandwidth to handle your average traffic load, it can be too small for peak traffic loads. Consider using separate interfaces for administrative traffic and for application traffic.

To estimate the network hardware required, calculate the size of the data returned to applications during peak load. For example, if you expect to have a peak load of 100,000 searches per second, each returning a full 8 KB entry, you require a network that can handle 800 MB/sec (3.2 Gb/sec) throughput, not counting other operations, such as replication traffic.

Storage

The directory server does not currently support network file systems such as NFS for database storage. Provide sufficient disk space on local storage such as internal disk or an attached disk array.

For a directory server, storage hardware must house both directory data, including historical data for replication, and server logs. On a heavily used server, you might improve performance by putting access logs on dedicated storage.

Storage must keep pace with throughput for write operations. Write throughput can arise from modify, modify DN, add, and delete operations, and from bind operations when a login timestamp is recorded, and when account lockout is configured, for example.

In a replicated topology, a directory server writes entries to disk when they are changed, and a replication server writes changelog entries. The server also records historical information to resolve potential replication conflicts.

For network throughput, base storage throughput required on peak loads rather than average loads.

Operating Systems

Directory Services 7.1 software is supported on the following operating systems:

Supported Host Operating Systems
Operating System Versions

Red Hat Enterprise Linux, Centos

7, 8

Amazon Linux

Amazon Linux 2018.03

SuSE

12, 15

Ubuntu

18.04 LTS, 20.04 LTS

Windows Server

2016, 2019

To avoid directory database file corruption after crashes or power failures on Linux systems, enable file system write barriers, and make sure that the file system journaling mode is ordered. For details on how to enable write barriers and set the journaling mode for data, see the options for your file system in the mount command manual page.

Maximum Open Files

DS servers must open many file descriptors when handling thousands of client connections.

Linux systems often set a limit of 1024 per user. That setting is too low to accept thousands of client connections.

Make sure the server can use at least 64K (65536) file descriptors. For example, when running the server as user opendj on a Linux system that uses /etc/security/limits.conf to set user level limits, set soft and hard limits by adding these lines to the file:

opendj soft nofile 65536
opendj hard nofile 131072

The example above assumes the system has enough file descriptors available overall. Check the Linux system overall maximum as follows:

$ cat /proc/sys/fs/file-max
204252

Maximum Watched Files

A directory server backend database monitors file events. On Linux systems, backend databases use the inotify API for this purpose. The kernel tunable fs.inotify.max_user_watches indicates the maximum number of files a user can watch with the inotify API.

Make sure this tunable is set to at least 512K:

$ sysctl fs.inotify.max_user_watches

fs.inotify.max_user_watches = 524288

If this tunable is set lower than that, update the /etc/sysctl.conf file to change the setting permanently, and use the sysctl -p command to reload the settings:

$ echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
[sudo] password for admin:

$ sudo sysctl -p
fs.inotify.max_user_watches = 524288

Antivirus Interference

Prevent antivirus and intrusion detection systems from interfering with DS software.

Before using DS software with antivirus or intrusion detection software, consider the following potential problems:

Interference with normal file access

Antivirus and intrusion detection systems that perform virus scanning, sweep scanning, or deep file inspection are not compatible with DS file access, particularly database file access.

Antivirus and intrusion detection software can interfere with the normal process of opening and closing database working files. They may incorrectly mark such files as suspect to infection due to normal database processing, which involves opening and closing files in line with the database’s internal logic.

Prevent antivirus and intrusion detection systems from scanning database and changelog database files.

At minimum, configure antivirus software to whitelist the DS server database files. By default, exclude the following file system directories from virus scanning:

  • /path/to/opendj/changelogDb/ (if replication is enabled)

    Prevent the antivirus software from scanning these changelog database files.

  • /path/to/opendj/db/

    Prevent the antivirus software from scanning database files, especially *.jdb files.

Port blocking

Antivirus and intrusion detection software can block ports that DS uses to provide directory services.

Make sure that your software does not block the ports that DS software uses. For details, see Administrative Access.

Negative performance impact

Antivirus software consumes system resources, reducing resources available to other services including DS servers.

Running antivirus software can therefore have a significant negative impact on DS server performance. Make sure that you test and account for the performance impact of running antivirus software before deploying DS software on the same systems.

Java

Directory Services software supports the following Java environments:

Supported Java Versions
Vendor Versions

OpenJDK, including OpenJDK-based distributions:

  • AdoptOpenJDK/Eclipse Adoptium

  • Amazon Corretto

  • Azul Zulu

  • Red Hat OpenJDK

ForgeRock tests most extensively with AdoptOpenJDK/Eclipse Adoptium.

ForgeRock recommends using the HotSpot JVM.

11

Oracle Java

11

ForgeRock recommends that you keep your Java installation up-to-date with the latest security fixes.

Make sure you have a required Java environment installed on the system. If your default Java environment is not appropriate, set OPENDJ_JAVA_HOME to the path to the correct Java environment, or set OPENDJ_JAVA_BIN to the absolute path of the java command.

Application Containers

The REST to LDAP and DSML gateway applications support the following web application containers:

Supported Web Application Containers
Container Versions

Apache Tomcat

8.5, 9

IBM WebSphere Liberty

20.0.0.1

JBoss Enterprise Application Platform

7.3

Wildfly

15, 19

Third-Party Software

ForgeRock provides support for using the following third-party software when logging ForgeRock Common Audit events:

Software Version

Java Message Service (JMS)

2.0 API

MySQL JDBC Driver Connector/J

8 (at least 8.0.19)

Splunk

8.0 (at least 8.0.2)

Elasticsearch and Splunk have native or third-party tools to collect, transform, and route logs. Examples include Logstash and Fluentd.

ForgeRock recommends that you consider these alternatives. These tools have advanced, specialized features focused on getting log data into the target system. They decouple the solution from the ForgeRock Identity Platform systems and version, and provide inherent persistence and reliability. You can configure the tools to avoid losing audit messages if a ForgeRock Identity Platform service goes offline, or delivery issues occur.

These tools can work with ForgeRock Common Audit logging:

  • Configure the server to log messages to standard output, and route from there.

  • Configure the server to log to files, and use log collection and routing for the log files.

ForgeRock provides support for using the following third-party software when monitoring ForgeRock servers:

Software Version

Grafana

5 (at least 5.0.2)

Graphite

1

Prometheus

2.0

For hardware security module (HSM) support, ForgeRock software requires a client library that conforms to the PKCS#11 standard v2.20 or later.

FQDNs

Directory Services replication requires the use of fully qualified domain names (FQDNs).

Hostnames like localhost or my-laptop.local are acceptable for evaluation.

When setting up and configuring production servers, use FQDNs, and ensure DNS is set up correctly to provide FQDNs.

As a workaround when demonstrating across multiple host systems, you can update the hosts file, /etc/hosts or C:\Windows\System32\drivers\etc\hosts, to specify FQDNs.

Examples in the documentation use the hostname localhost to contact local DS servers. Trust in the examples depends on the use of a deployment key and password when setting up servers. A server certificate generated from a deployment key and password has localhost as the default hostname. By using the --hostname localhost option with a DS command-line tool, you simplify the secure connection process. When the tool validates the specified hostname against the hostname in the server certificate, they match. There is no need to add the server’s hostname to the server certificate.

When making a secure connection to a remote server, be sure the FQDN in the --hostname fqdn option matches a valid hostname in the server certificate. If the server certificate is generated with a deployment key and password, you can easily renew the certificate to change or add a hostname. For examples, see Replace a TLS Key Pair or Generate a Key Pair (Wildcard Certificate).

Adapt the examples as necessary when using your own certificates, keys, and PKI.

Clock Synchronization

Before using DS replication, set up synchronization between server system clocks.

To keep the system clocks synchronized, use a process that adjusts time to eventual clock consistency, such as ntpd. NTP adjusts the size of a second to move time to eventual clock consistency.

Once you have enabled replication, avoid moving the system clock in large increments, such as more than half a day at a time, or possibly less for systems under high load.

Certificates

For secure network communications with client applications that you do not control, install a properly signed digital certificate that your client applications recognize, such as one that works with your organization’s PKI, or one signed by a recognized CA.

To use the certificate during installation, the certificate must be located in a file-based keystore supported by the JVM (JKS, JCEKS, PKCS#12), or on a PKCS#11 token. To import a signed certificate into the server keystore, use the Java keytool command.

For details, see Key Management.