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.
The ForgeRock BackStage download site provides access to ForgeRock releases. ForgeRock 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.
| || |
Cross-platform distribution of the server software.
Pure Java, high-performance server that can be configured as:
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
| || |
Microsoft Windows native installer for the server software.
By default, this installs files into a
| || |
Server software native packages for Debian and related Linux distributions.
By default, this installs files into an
| || |
Server software native packages for Red Hat and related Linux distributions.
By default, this installs files into an
| || |
Cross-platform DSML gateway web archive.
| || |
Cross-platform REST to LDAP gateway web archive.
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.
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, read the rest of this section.
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.
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".
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.
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.
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.
As for network throughput, base storage throughput required on peak loads rather than average loads.
Directory Services 7 software is supported on the following operating systems:
|Red Hat Enterprise Linux, Centos||7, 8|
|Amazon Linux||Amazon Linux 2018.03|
|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 handle to handle 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:
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:
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
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.
Prevent the antivirus software from scanning database files, especially
- 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.
Directory Services software supports the following Java environments:
OpenJDK, including OpenJDK-based distributions:
ForgeRock tests most extensively with AdoptOpenJDK/Eclipse Adoptium.
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.
The REST to LDAP and DSML gateway applications support the following web application containers:
|Apache Tomcat||8.5, 9|
|IBM WebSphere Liberty||184.108.40.206|
|JBoss Enterprise Application Platform||7.2|
ForgeRock provides support for using the following third-party software when logging ForgeRock Common Audit events:
|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)|
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:
|Grafana||5 (at least 5.0.2)|
For hardware security module (HSM) support, ForgeRock software requires a client library that conforms to the PKCS#11 standard v2.20 or later.
Directory Services replication requires the use of fully qualified domain names (FQDNs).
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 (
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.
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.
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".