Installation
This guide shows you how to install and remove PingDS software.
Component | Description |
---|---|
Directory server and tools |
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. |
DSML gateway (deprecated) |
DSML support is available through the gateway, which is a Java web application that you install in a web container. |
HDAP gateway |
The HDAP gateway is a Java web application offering REST access to a remote LDAPv3 directory service. |
Java APIs |
Java server-side APIs for server plugins that extend directory services. All Java APIs have interface stability: Evolving. Be prepared for incompatible changes in both major and minor releases. |
Read the Release notes before installing DS software.
Product names changed when ForgeRock became part of Ping Identity. PingDS was formerly known as ForgeRock Directory Services, for example. Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.
Unpack files
The following procedures only unpack the server files.
You must then run the setup
command to set up the server:
Unpack the cross-platform zip
You can use the .zip delivery on any supported operating system.
-
Unpack the cross-platform .zip file in the file system directory where you want to install the server.
Perform this step as a user with the same file system permissions as the user who will run the
setup
command.The
setup
command uses the directory where you unzipped the files as the installation directory. It does not ask you where to install the server. If you want to install elsewhere on the file system, unzip the files in that location.
Use the Debian package
On Debian and related Linux distributions, such as Ubuntu, you can unpack files using the Debian package:
-
Review requirements for installation.
In particular, install a Java runtime environment (JRE) if none is installed yet. The following example uses the
java11-runtime
virtual package:$ sudo apt-get install java11-runtime
-
Install the server package:
$ sudo dpkg -i DS*.deb
The Debian package:
-
Installs server files in the
/opt/opendj
directory. -
Adds documentation files under the
/usr/share/doc/opendj
directory. -
Adds man pages under the
/opt/opendj/share/man
directory. -
Generates systemd service files
/etc/default/opendj
and/etc/systemd/system/opendj.service
.
By default, the system superuser (
root
) owns the files. The DS server can listen on privileged ports like389
and636
. -
-
(Optional) Change the systemd configuration:
-
Edit
/etc/default/opendj
directly to set any environment variables DS requires.For example, set environment variables for property value substitutions.
-
Use the
systemctl edit
command to change the service configuration; for example, to run DS as a specific user.The command makes the changes in a new
override.conf
file that systemd reads automatically.
The changes you make in this way are independent of upgrades and changes to the package defaults. To avoid compatibility problems, don’t edit
/etc/systemd/system/opendj.service
directly. -
-
Set up the server with the
setup
command,sudo /opt/opendj/setup
.
Use the RPM package
On Red Hat and related Linux distributions, such as Fedora and CentOS, you can unpack files using the RPM package:
-
Review requirements for installation.
In particular, install a Java runtime environment (JRE) if none is installed yet. You might need to download an RPM to install the Java runtime environment, and then install the RPM by using the
rpm
command:$ su Password: root# rpm -ivh jre-*.rpm
-
Install the server package:
root# rpm -i DS*.rpm
The RPM package:
-
Installs server files in the
/opt/opendj
directory. -
Adds man pages under the
/opt/opendj/share/man
directory. -
Generates systemd service files
/etc/default/opendj
and/etc/systemd/system/opendj.service
.
By default, the system superuser (
root
) owns the files. The DS server can listen on privileged ports like389
and636
. -
-
(Optional) Change the systemd configuration:
-
Edit
/etc/default/opendj
directly to set any environment variables DS requires.For example, set environment variables for property value substitutions.
-
Use the
systemctl edit
command to change the service configuration; for example, to run DS as a specific user.The command makes the changes in a new
override.conf
file that systemd reads automatically.
The changes you make in this way are independent of upgrades and changes to the package defaults. To avoid compatibility problems, don’t edit
/etc/systemd/system/opendj.service
directly. -
-
Set up the server with the
setup
command,/opt/opendj/setup
.By default, the server starts in run levels 2, 3, 4, and 5.
Use the Windows MSI
Make sure you can log on as Windows Administrator to install the files and run the setup.bat
command.
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:
|
GUI
-
Start the wizard as Windows Administrator:
-
If you are logged on as Administrator, double-click the Windows installer package,
DS-7.5.1.msi
. -
If you are logged on as a regular user, hold the shift key while right-clicking
DS-7.5.1.msi
, select Run as different user, and run the installer as Windows Administrator.
-
-
(Optional) Set the Destination Folder to the location for DS server files.
-
The default location is under
Program Files
on the system drive.For example, if the system drive is
C:
, the default location isC:\Program Files (x86)\ForgeRock Directory Services\
. -
The Windows installer has 32-bit dependencies but DS runs as a 64-bit Java application.
-
Complete the wizard.
The installation program writes DS server files to the destination folder.
You must run the
setup.bat
command in the destination folder as Administrator to set up DS.
-
PowerShell
-
Start PowerShell as Windows Administrator:
-
If you are logged on as Windows Administrator, double-click Start > Windows PowerShell.
-
If you are logged on as a regular user, hold the shift key while right-clicking Start > Windows PowerShell and select Run as Administrator.
-
-
Use the Microsoft
msiexec.exe
command to install the files.The following example installs DS server files under
C:\Users\opendj\ds
. It writes aninstall.log
file in the current folder:C:\> msiexec /i C:\Users\opendj\Downloads\DS-7.5.1.msi /l* install.log /q OPENDJ="C:\Users\opendj\ds"
The installation program writes DS server files to the destination folder.
You must run the
setup.bat
command in the destination folder as Administrator to set up DS.
Setup hints
The following table provides extensive hints for using setup
command options
in the order they are presented in interactive mode, when you run the command without options.
For reference information, refer to setup:
Parameter | Description | Option(s) |
---|---|---|
Instance path |
Server setup uses tools and templates installed with the software to generate the instance files required to run an instance of a server. By default, all the files are co-located. This parameter lets you separate the files. Set the instance path to place generated files in a different location from the tools, templates, and libraries you installed. Interactive setup suggests co-locating the software with the instance files. You cannot use a single software installation for multiple servers. Tools for starting and stopping the server process, for example, work with a single configured server. They do not have a mechanism to specify an alternate server location. If you want to set up another server, install another copy of the software,
and run that copy’s |
|
Unique server ID |
A server identifier string that is unique for your deployment. Choose a relatively short string, as the value is recorded repeatedly in replicated historical data. |
|
Deployment ID |
The deployment ID is a random string generated using the Together, the deployment ID and password serve to generate the shared master key that DS servers in the deployment require for protecting shared encryption secrets. By default, they also serve to generate a private CA and keys for TLS to protect communication between DS servers. When you deploy multiple servers together, reuse the same deployment ID and password for each server installation. For details, refer to Deployment IDs. |
|
Deployment ID password |
This is a random string that you choose, and that you must keep secret. It is paired with the deployment ID. |
|
Root user DN |
The root user DN identifies the initial directory superuser. This user has privileges to perform any and all administrative operations, and is not subject to access control. It is called the root user due to the similarity to the Linux root user. The default name is: For additional security in production environments, use a different name. |
|
Root user password |
The root user authenticates with simple, password-based authentication. Use a strong password here unless this server is only for evaluation. |
|
Monitor user DN |
The monitor user DN identifies a user with the privilege to read monitoring data ( The account is replicated by default, so use the same DN on each server. The name used in the documentation is the default name: |
|
Monitor user password |
The monitor user authenticates with simple, password-based authentication. The account is replicated by default, so use the same password on each server. |
|
Fully qualified directory server domain name |
The server uses the fully qualified domain name (FQDN) for identification between replicated servers. Interactive setup suggests the hostname of the local host. If this server is only for evaluation, then you can use Otherwise, use an FQDN that other hosts can resolve to reach your server, and that matches the FQDN in the server certificate. |
|
Administration port |
This is the service port used to configure the server and to run tasks. The port used in the documentation is If the suggested port is not free, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. Configure the firewall to allow access to this port from all connecting DS servers. |
|
Securing the deployment |
Setup requires a keystore with the keys for securing connections to the administration port, and to any other secure ports you configure during setup. You can choose to use the private PKI derived from the deployment ID and passwords. For details, refer to Deployment IDs. You can also choose to use an existing keystore supported by the JVM,
which can be either a file-based keystore or a PKCS#11 token.
The existing keystore must protect the keystore and all private keys with the same PIN or password.
If you choose a PKCS#11 token, you must first configure access through the JVM,
as the only input to the Public key security is often misunderstood. Before making security choices for production systems, read Cryptographic keys. |
|
Start the server |
By default, the If no further configuration is required, use the |
|
LDAP and LDAPS port |
The reserved port for LDAP is Examples in the documentation use If you install the server with access to privileged ports (< The LDAP StartTLS extended operation negotiates a secure connection starting on the insecure LDAP port. |
|
HTTP and HTTPS ports |
The reserved port for HTTP is If the initially suggested port is not free or cannot be used due to lack of privileges, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. Examples in the documentation use HTTPS on port |
|
Replication port |
Port used for data replication messages. This port must be accessible externally from other DS servers. If this port is configured, the server acts as a replication server. It maintains a replication change log, which it exposes as an external change log by default. If the initially suggested port is not free or cannot be used due to lack of privileges, interactive setup adds 1000 to the port number and tries again, repeatedly adding 1000 until a free port is found. Examples in the documentation use |
|
Bootstrap replication servers |
Specify bootstrap server Specify the same list of bootstrap servers each time you set up a replica or standalone replication server. This option interacts with the
|
|
Configure the server for use with other applications |
For details, refer to Setup profiles. |
|
Setup profiles
A setup profile lets you configure a server for a specific use case. Profiles greatly simplify the directory server setup process for such use cases, such as preparing a directory server to serve another Ping Identity Platform component product.
You can configure a setup profile using the setup
command,
or the setup-profile
command after initial setup.
The setup-profile
command runs on a server that is offline.
Select a profile with the --profile
option.
Each profile has its own parameters, some of which have default values.
You specify profile parameters with --set
options.
The profile selection option takes the form
--profile profileName[:version]
.
If you do not specify the optional :version
portion of the argument,
the setup
command uses the current DS software version,
falling back to the previous version if the current version does not match an available profile.
Repeat the --profile
option to apply multiple setup profiles.
An option to set a parameter takes the form
--set[:env|:file] parameterName:value
where:
-
profileName/
indicates which profile the parameter applies to.This name is required when you specify multiple profiles, and the parameter is available in more than one of the specified profiles.
The
profileName
is case-insensitive. -
parameterName
specifies the parameter to set. -
value
specifies the value the parameter takes when thesetup
command applies the profile.
Use the setup --help-profiles
or setup-profile --help
command to list available profiles.
Use the --help-profile profileName[:version]
option
to list the parameters for the specified profile.
Different data under different base DNs
Nothing prevents you from configuring multiple setup profiles to use the same base DN for different directory data. Keep different directory data under different base DNs.
When the different data sets are incompatible, reusing a base DN can lead to errors, such as the following:
category=CONFIG severity=ERROR msgID=116 msg=An error occurred while trying to initialize a backend loaded from class org.opends.server.backends.jeb.JEBackend with the information in configuration entry ds-cfg-backend-id=cfgStore,cn=Backends,cn=config: An error occurred while attempting to register the base DNs [dc=reused,dc=base,dc=dn] in the Directory Server: Unwilling to Perform: Unable to register base DN dc=reused,dc=base,dc=dn with the Directory Server for backend cfgStore because that base DN is already registered for backend amCts. This backend will be disabled.
Check profiles
The opendj/profiles.version
file lists the profiles selected at setup time:
$ cat /path/to/opendj/config/profiles.version
ds-evaluation:7.5.1
Default Setup Profiles
This page lists default profiles with their parameters.
AM Configuration Data Store 6.5.0
The am-config:6.5.0
profile has the following parameters:
backendName
-
Name of the backend for storing config
Default:--set am-config/backendName:cfgStore
Syntax: Name baseDn
-
The base DN to use to store AM’s configuration in
Default:--set am-config/baseDn:ou=am-config
Syntax: DN amConfigAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password
AM CTS Data Store 6.5.0
The am-cts:6.5.0
profile has the following parameters:
backendName
-
Name of the backend for storing tokens
Default:--set am-cts/backendName:amCts
Syntax: Name baseDn
-
The base DN to use to store AM’s tokens in
Default:--set am-cts/baseDn:ou=tokens
Syntax: DN amCtsAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password tokenExpirationPolicy
-
Token expiration and deletion
Default:--set am-cts/tokenExpirationPolicy:am
This parameter takes one of the following values:-
am
: AM CTS reaper manages token expiration and deletion -
am-sessions-only
: AM CTS reaper manages SESSION token expiration and deletion. DS manages expiration and deletion for all other token types. AM continues to send notifications about session expiration and timeouts to agents -
ds
: DS manages token expiration and deletion. AM session-related functionality is impacted and notifications are not sent
-
AM Identity Data Store 7.5.0
The am-identity-store:7.5.0
profile has the following parameters:
backendName
-
Name of the backend for storing identities
Default:--set am-identity-store/backendName:amIdentityStore
Syntax: Name baseDn
-
The base DN to use to store identities in
Default:--set am-identity-store/baseDn:ou=identities
Syntax: DN amIdentityStoreAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password
AM Identity Data Store 7.3.0
The am-identity-store:7.3.0
profile has the following parameters:
backendName
-
Name of the backend for storing identities
Default:--set am-identity-store/backendName:amIdentityStore
Syntax: Name baseDn
-
The base DN to use to store identities in
Default:--set am-identity-store/baseDn:ou=identities
Syntax: DN amIdentityStoreAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password
AM Identity Data Store 7.2.0
The am-identity-store:7.2.0
profile has the following parameters:
backendName
-
Name of the backend for storing identities
Default:--set am-identity-store/backendName:amIdentityStore
Syntax: Name baseDn
-
The base DN to use to store identities in
Default:--set am-identity-store/baseDn:ou=identities
Syntax: DN amIdentityStoreAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password
AM Identity Data Store 7.1.0
The am-identity-store:7.1.0
profile has the following parameters:
backendName
-
Name of the backend for storing identities
Default:--set am-identity-store/backendName:amIdentityStore
Syntax: Name baseDn
-
The base DN to use to store identities in
Default:--set am-identity-store/baseDn:ou=identities
Syntax: DN amIdentityStoreAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password
AM Identity Data Store 7.0.0
The am-identity-store:7.0.0
profile has the following parameters:
backendName
-
Name of the backend for storing identities
Default:--set am-identity-store/backendName:amIdentityStore
Syntax: Name baseDn
-
The base DN to use to store identities in
Default:--set am-identity-store/baseDn:ou=identities
Syntax: DN amIdentityStoreAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password
AM Identity Data Store 6.5.0
The am-identity-store:6.5.0
profile has the following parameters:
backendName
-
Name of the backend for storing identities
Default:--set am-identity-store/backendName:amIdentityStore
Syntax: Name baseDn
-
The base DN to use to store identities in
Default:--set am-identity-store/baseDn:ou=identities
Syntax: DN amIdentityStoreAdminPassword
-
Password of the administrative account that AM uses to bind to OpenDJ
Syntax: Password
DS Evaluation 7.5.0
The ds-evaluation:7.5.0
profile has the following parameters:
generatedUsers
-
Specifies the number of generated user entries to import. The evaluation profile always imports entries used in documentation examples, such as uid=bjensen. Optional generated users have RDNs of the form uid=user.%d, yielding uid=user.0, uid=user.1, uid=user.2 and so on. All generated users have the same password, "password". Generated user entries are a good fit for performance testing with tools like addrate and searchrate
Default:--set ds-evaluation/generatedUsers:100000
Syntax: Number useOutdatedPasswordStorage
-
Use Salted SHA-512 as the password storage scheme for the import and default password policy for users.
Default:--set ds-evaluation/useOutdatedPasswordStorage:false
This parameter takes one of the following values:-
true
-
false
-
DS Proxied Server 7.0.0
The ds-proxied-server:7.0.0
profile has the following parameters:
proxyUserDn
-
The proxy user service account DN. This will be used for authorization and auditing proxy requests.
Default:--set ds-proxied-server/proxyUserDn:uid=proxy
Syntax: DN proxyUserCertificateSubjectDn
-
The subject DN of the proxy user’s certificate. The proxy must connect using mutual TLS with a TLS client certificate whose subject DN will be mapped to the proxy service account.
Default:--set ds-proxied-server/proxyUserCertificateSubjectDn:CN=DS,O=ForgeRock.com
Syntax: DN baseDn
-
Base DN for user information in the server. Multiple base DNs may be provided by using this option multiple times. If no base DNs are defined then the server will allow proxying as any user, including administrator accounts.
Syntax: DN
DS Proxy Server 7.0.0
The ds-proxy-server:7.0.0
profile has the following parameters:
backendName
-
Name of the proxy backend for storing proxy configuration
Default:--set ds-proxy-server/backendName:proxyRoot
Syntax: Name bootstrapReplicationServer
-
Bootstrap replication server(s) to contact periodically in order to discover remote servers
Syntax: host:port or configuration expression rsConnectionSecurity
-
Connection security type to use to secure communication with remote servers
Default:--set ds-proxy-server/rsConnectionSecurity:ssl
This parameter takes one of the following values:-
ssl
: Use SSL -
start-tls
: Use Start TLS
-
keyManagerProvider
-
Name of the key manager provider used for authenticating the proxy in mutual-TLS communications with backend server(s)
Default:--set ds-proxy-server/keyManagerProvider:PKCS12
Syntax: Name or configuration expression trustManagerProvider
-
Name of the trust manager provider used for trusting backend server(s) certificate(s)
Syntax: Name or configuration expression certNickname
-
Nickname(s) of the certificate(s) that should be sent to the server for SSL client authentication.
Default:--set ds-proxy-server/certNickname:ssl-key-pair
Syntax: Name or configuration expression primaryGroupId
-
Replication domain group ID of directory server replicas to contact when available before contacting other replicas. If this option is not specified then all replicas will be treated the same (i.e all remote servers are primary)
Syntax: String or configuration expression baseDn
-
Base DN for user information in the Proxy Server.Multiple base DNs may be provided by using this option multiple times.If no base DNs are defined then the proxy will forward requests to all public naming contexts of the remote servers
Syntax: DN or configuration expression
DS User Data Store 7.0.0
The ds-user-data:7.0.0
profile has the following parameters:
backendName
-
Name of the backend to be created by this profile
Default:--set ds-user-data/backendName:userData
Syntax: Name baseDn
-
Base DN for your users data.
Syntax: DN ldifFile
-
Path to an LDIF file containing data to import. Use this option multiple times to specify multiple LDIF files
Syntax: File or directory path addBaseEntry
-
Create entries for specified base DNs when the 'ldifFile' parameter is not used. When this option is set to 'false' and the 'ldifFile' parameter is not used, create an empty backend.
Default:--set ds-user-data/addBaseEntry:true
This parameter takes one of the following values:-
true
-
false
-
IDM External Repository 7.5.0
The idm-repo:7.5.0
profile has the following parameters:
backendName
-
IDM repository backend database name
Default:--set idm-repo/backendName:idmRepo
Syntax: Name domain
-
Domain name translated to the base DN for IDM external repository data. Each domain component becomes a "dc" (domain component) of the base DN. This profile prefixes "dc=openidm" to the result. For example, the domain "example.com" translates to the base DN "dc=openidm,dc=example,dc=com".
Default:--set idm-repo/domain:example.com
Syntax: Domain name
IDM External Repository 7.4.0
The idm-repo:7.4.0
profile has the following parameters:
backendName
-
IDM repository backend database name
Default:--set idm-repo/backendName:idmRepo
Syntax: Name domain
-
Domain name translated to the base DN for IDM external repository data. Each domain component becomes a "dc" (domain component) of the base DN. This profile prefixes "dc=openidm" to the result. For example, the domain "example.com" translates to the base DN "dc=openidm,dc=example,dc=com".
Default:--set idm-repo/domain:example.com
Syntax: Domain name
IDM External Repository 7.3.0
The idm-repo:7.3.0
profile has the following parameters:
backendName
-
IDM repository backend database name
Default:--set idm-repo/backendName:idmRepo
Syntax: Name domain
-
Domain name translated to the base DN for IDM external repository data. Each domain component becomes a "dc" (domain component) of the base DN. This profile prefixes "dc=openidm" to the result. For example, the domain "example.com" translates to the base DN "dc=openidm,dc=example,dc=com".
Default:--set idm-repo/domain:example.com
Syntax: Domain name
IDM External Repository 7.2.0
The idm-repo:7.2.0
profile has the following parameters:
backendName
-
IDM repository backend database name
Default:--set idm-repo/backendName:idmRepo
Syntax: Name domain
-
Domain name translated to the base DN for IDM external repository data. Each domain component becomes a "dc" (domain component) of the base DN. This profile prefixes "dc=openidm" to the result. For example, the domain "example.com" translates to the base DN "dc=openidm,dc=example,dc=com".
Default:--set idm-repo/domain:example.com
Syntax: Domain name
IDM External Repository 7.1.0
The idm-repo:7.1.0
profile has the following parameters:
backendName
-
IDM repository backend database name
Default:--set idm-repo/backendName:idmRepo
Syntax: Name domain
-
Domain name translated to the base DN for IDM external repository data. Each domain component becomes a "dc" (domain component) of the base DN. This profile prefixes "dc=openidm" to the result. For example, the domain "example.com" translates to the base DN "dc=openidm,dc=example,dc=com".
Default:--set idm-repo/domain:example.com
Syntax: Domain name
IDM External Repository 7.0.0
The idm-repo:7.0.0
profile has the following parameters:
backendName
-
IDM repository backend database name
Default:--set idm-repo/backendName:idmRepo
Syntax: Name domain
-
Domain name translated to the base DN for IDM external repository data. Each domain component becomes a "dc" (domain component) of the base DN. This profile prefixes "dc=openidm" to the result. For example, the domain "example.com" translates to the base DN "dc=openidm,dc=example,dc=com".
Default:--set idm-repo/domain:example.com
Syntax: Domain name
IDM External Repository 6.5.0
The idm-repo:6.5.0
profile has the following parameters:
backendName
-
IDM repository backend database name
Default:--set idm-repo/backendName:idmRepo
Syntax: Name domain
-
Domain name translated to the base DN for IDM external repository data. Each domain component becomes a "dc" (domain component) of the base DN. This profile prefixes "dc=openidm" to the result. For example, the domain "example.com" translates to the base DN "dc=openidm,dc=example,dc=com".
Default:--set idm-repo/domain:example.com
Syntax: Domain name
Create your own
If you have changes that apply to each server you set up, you can create and maintain your own setup profile.
The custom setup profile interface has stability: Evolving. Be prepared to adapt your custom profiles to changes in each new release. |
-
Add custom setup profiles under the
opendj/template/setup-profiles/
directory.The
setup
andsetup-profile
commands look for profiles in that location. The default profiles provide examples that you can follow when building custom profiles. -
Add custom setup profiles after unpacking the DS files, but before running the
setup
orsetup-profile
command. -
Each setup profile strictly follows the supported file layout.
The base path, version directories, and the
.groovy
files are required. The other files are shown here as examples:
opendj/template/setup-profiles/base-path/
├── version
│ ├── base-entries.ldif
│ ├── parameters.groovy
│ ├── profile.groovy
│ └── schema
│ └── schema-file-name.ldif
└── name.txt
File or Directory | Description |
---|---|
|
The base path distinguishes the profile from all other profiles, and defines the profile name. Path separator characters are replaced with dashes in the name.
For example, the base path |
|
The profile version, including either two or three numbers.
Numbers can be separated by dots ( Set this to the version of the software that the profile is for.
For example, if you are writing a profile for Transmogrifier 2.0, use |
|
Optional LDIF file that templates the entries this profile adds to the directory. This is an example of a file used by |
|
Groovy script defining profile parameters that users can set. Refer to Parameters. |
|
Groovy script that makes changes to the server. Refer to Profile script. |
|
Optional LDAP schema file required for entries added by this profile. This is an example of a file used by |
|
If this file is present, it must hold the human-readable form of the profile name, not including the version, in a single-line text file. |
At setup time, the user cannot select more than one version of the same setup profile. The user can select multiple setup profiles for the same server. You must ensure that your profile is not incompatible with other available profiles.
Parameters
You let users set parameters through the parameters.groovy
script.
The profile uses the parameters as variables in the profile.groovy
script, and resource files.
The parameters.groovy
script lists all parameter definitions for the profile.
It includes only parameter definitions.
Each parameter definition is resolved at runtime, and so must not be provided programmatically.
Parameter definitions start with define
, and can have the following methods:
define.type "name" \
advanced() \
defaultValueFromSetupTool global-setup-option \
defaultValue default \
description "short-description" \
help "help-message" \
multivalued() \
multivalued "help message(s)" \
optional() \
optional "help message(s)" \
descriptionIfNoValueSet "short-description" \
property "property-name" \
prompt "prompt message(s)" \
expressionAllowed()
Element | Description |
---|---|
|
This mandatory parameter type is one of the following. The profile mechanism converts the string input internally into a Java class:
|
|
This mandatory parameter name must be a valid Groovy name string. |
|
This is an advanced parameter, meaning interactive mode does not show the parameter or prompt for input. When using |
|
This parameter takes its default from the value of the specified the global The global-setup-option is the option name without leading dashes. |
|
This parameter’s default must match the type. |
|
This provides a brief summary of what the parameter does. The "short-description" is a single paragraph with no trailing punctuation. |
|
The message, used in online help, provides further explanation on how to use the parameter. The "help-message" is a single paragraph with no trailing punctuation. |
|
This parameter takes multiple values, and no help message is required. Use this, for example, when the property is |
|
This parameter takes multiple values, and interactive mode prompts the user for each one. Each help message string is a single paragraph, and the final help message has no trailing punctuation. Help message arguments are separated with commas. |
|
This parameter is optional, and no help message is required. |
|
This parameter is optional, and interactive mode prompts the user for input. Each help message string is a single paragraph, and the final help message has no trailing punctuation. Help message arguments are separated with commas. |
|
The description is displayed when the parameter is optional, and the user has not set a value. The "short-description" is a single paragraph with no trailing punctuation. |
|
The profile replaces The |
|
In interactive mode, display one or more paragraphs when prompting the user for input. Each prompt message string is a single paragraph. If no default value is set the final prompt message takes a trailing colon. Prompt message arguments are separated with commas. |
Profile script
When a user requests a profile, the profile.groovy
script controls what the profile does.
When developing your profile script, you can use these classes and methods, which are bound into the execution context of your script before it executes:
In addition, refer to the Javadoc for the setup model.
Default imports
The profile mechanism imports the following classes and methods, making them available by default in the context of your profile script:
import static org.forgerock.i18n.LocalizableMessage.raw
import static org.forgerock.opendj.setup.model.Profile.ParameterType.of
import static java.nio.file.Files.*
import org.forgerock.i18n.LocalizableMessage
import org.forgerock.opendj.ldap.Dn
import org.forgerock.opendj.setup.model.SetupException
import java.nio.file.Paths
Server methods
A ds
object is bound into the execution context of your profile script.
All its methods throw a SetupException
on failure.
On failure, the setup process removes the server’s db
and config
directories.
This allows the user to start over, applying the same profiles again.
All the ds
methods run with the server offline:
Method | Description |
---|---|
|
Creates the backend, adds it to the server, and sets it as the working backend. When you use other methods to import LDIF and create indexes, they operate on the working backend. Use |
|
|
|
|
|
|
|
Set the specified backend as the one to operate on when importing LDIF and creating indexes. |
|
Import the entry with the specified base DN as the base entry of the working backend. The import operation erases any previous content of the backend before importing new content. |
|
Import the specified number of sample entries with the specified base DN, based on the LDIF file templates provided, to the working backend. The LDIF must contain the base entry. This method replaces The import operation erases any previous content of the backend before importing new content. |
|
Add the entries from the LDIF files provided to the working backend. The LDIF must contain the base entry. This method replaces The import operation erases any previous content of the backend before importing new content. |
|
|
|
Add the entries from the LDIF files provided to the working backend. The LDIF must contain the base entry. If there are multiple files, each entry must appear only once. The import operation erases any previous content of the backend before importing new content. |
|
|
|
Copy LDIF-format schema files from the If no |
|
Run the Use this method only for additional configuration, not when creating backends or indexes. |
|
Create indexes of the specified types in the working backend for the specified attribute. For a list of available index types, refer to index-type. |
|
Cause the profile to fail with a |
Resource file methods
A resource
object is bound into the execution context of your profile script.
The resource
methods let you retrieve arbitrary files from the profile,
and replace configuration expressions in resource files:
Method | Description |
---|---|
|
Return the path to the specified resource file. If the specified path is relative, the method first returns the path of the file in the current profile version, or the path of the file in the previous profile version if none is present in the current version. If the specified path is absolute, the method only converts the string to a path. |
|
Convert the relative template path as The |
Logging methods
Use the console
object to write log messages when your profile script runs.
The console
object implements SetupConsole,
and so provides all the methods documented for that interface.
The setup
and setup-profile
commands log any exceptions that occur
when your profile script runs, so there is no need to catch exceptions just for logging purposes.
Install DS for evaluation
More information
To set up the server, use the setup command-line tool.
When used without options, the command is interactive.
The following setup
options are mandatory.
When performing a non-interactive, silent installation, specify at least all mandatory options as part of the command.
If you use only these options, the command sets up a server listening only on an administration port.
The administration port is protected by a key pair specified or generated at setup time:
-
--adminConnectorPort {port}
(conventional port number:4444
) -
--hostname {hostname}
-
--rootUserDN {rootUserDN}
(default:uid=admin
) -
--rootUserPassword {rootUserPassword}
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Generate a deployment ID unless you already have one:
$ /path/to/opendj/bin/dskeymgr create-deployment-id --deploymentIdPassword password your-deployment-id
Save the deployment ID and its deployment password. Keep the ID and the password safe, and keep the password secret. Use the same deployment ID and password for all the servers in the same environment.
More about deployment IDs
A deployment ID is a random string generated using the
dskeymgr
command. It is a deployment identifier, not a key, but it is used with a password to generate keys.A deployment ID password is a secret string at least 8 characters long that you choose.
The two are a pair. You must have the deployment ID password to use the deployment ID.
Each deployment requires a single, unique deployment ID and its password. DS uses the pair to:
-
Protect the keys to encrypt and decrypt backup files and directory data.
-
Generate the TLS key pairs to protect secure connections, unless you provide your own.
Store your deployment ID and password in a safe place, and reuse them when configuring other servers in the same deployment.
The DS
setup
anddskeymgr
commands use the pair to generate the following:-
(Required) A shared master key for the deployment.
DS replicas share secret keys for data encryption and decryption. DS servers encrypt backend data, backup files, and passwords, and each replica must be able to decrypt data encrypted on another peer replica.
To avoid exposing secret keys, DS servers encrypt secret keys with a shared master key. DS software uses a deployment ID and its password to derive the master key.
-
(Optional) A private PKI for trusted, secure connections.
A PKI serves to secure network connections from clients and other DS servers. The PKI is a trust network, requiring trust in the CA that signs public key certificates.
Building a PKI can be complex. You can use self-signed certificates, but you must distribute each certificate to each server and client application. You can pay an existing CA to sign certificates, but that has a cost, and leaves control of trust with a third party. You can set up a CA or certificate management software, but that can be a significant effort and cost. As a shortcut to setting up a private CA, DS software uses deployment IDs and passwords.
DS software uses the deployment ID and its password to generate key pairs without storing the CA private key.
For additional details, refer to Deployment IDs.
-
-
Set the deployment ID as the value of the environment variable,
DEPLOYMENT_ID
:$ export DEPLOYMENT_ID=your-deployment-id
Examples in the documentation show this environment variable as a reminder to use your own key. Other options are available, as described by the
setup --help
command. -
Run the
setup
command to install a directory server replica with the evaluation profile:# Set up a directory server for evaluation. $ /path/to/opendj/setup \ --serverId evaluation-only \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword password \ --monitorUserPassword password \ --hostname localhost \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer localhost:8989 \ --profile ds-evaluation \ --start \ --acceptLicense
More information
-
The
setup
command is located where you installed the files. -
The setup process uses the deployment ID you generated, and its password.
If you specify only a deployment password, and no deployment ID, the
setup
command generates a deployment ID and displays it in the output. -
This example prepares a single server for evaluation, so the hostname is
localhost
.In production, use fully qualified domain names, such as
ds.example.com
. -
The server is ready to replicate sample data with other servers, but there are no other replicas, yet.
For now, the server points to itself as a bootstrap replication server. To get started with replication, refer to Learn replication.
-
It sets a password for the default monitoring user account,
uid=Monitor
. -
The server listens for requests on the ports used in examples throughout the documentation.
-
For evaluation purposes, no further configuration is required.
The
--start
option forces the server to start as part of the setup process.
-
Learn about the evaluation setup profile
The evaluation setup profile helps you learn and demonstrate directory services. Unlike other setup profiles, which use secure, production-ready access control settings, the evaluation setup profile provides easy access to sample data with the following features:
-
Sample Example.com data.
The sample data has the base DN
dc=example,dc=com
. It includes more than 100 hand-written entries for users, groups, and devices.By default, it also includes 100,000 generated users, with DNs from
uid=user.0,ou=people,dc=example.dc=com
touid=user.99999,ou=people,dc=example.dc=com
.Use the
--set ds-evaluation/generatedUsers:number
option to generate a different number of additional entries. Each generated user has the same password, which ispassword
.The hand-written sample Example.com data includes a group of directory administrators,
cn=Directory Administrators,ou=Groups,dc=example,dc=com
. Members of this group, such askvaughan
, have full access to directory data.Examples throughout the documentation demonstrate features using this sample data.
-
Global permission to perform operations over insecure connections.
-
HDAP enabled by default.
-
Additional schema for examples demonstrating class of service and JSON attributes.
-
Custom matching rule providers for JSON attributes.
-
Many permissions, such as anonymous read and search access, listed in the table that follows.
The evaluation setup profile lets you learn and demonstrate most directory features without adding any ACIs.
Name | Description | ACI definition |
---|---|---|
Anonymous extended operation access |
Anonymous and authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications. |
|
Anonymous extended operation access |
Anonymous and authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications. |
|
Anonymous read and search access |
Anonymous and authenticated Example.com users can read the user data attributes that are specified by their names. |
|
Authenticated control use |
Authenticated Example.com users can proxy and examine CSNs. |
|
Authenticated users extended operation access |
Authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications. |
|
Authenticated users extended operation access |
Authenticated users can request the LDAP extended operations that are specified by OID or alias. Modification or removal may affect applications. |
|
Directory administrator full access |
Example.com directory administrators have access to read and write Example.com directory data, rename and move entries, and use proxied authorization. |
|
Proxied authorization for apps |
Example.com applications can make requests on behalf of other users. |
|
Self entry modification |
Authenticated users can modify the specified attributes on their own entries. |
|
Self entry read for passwords |
Authenticated users can read the password values on their own entries. By default, the server applies a one-way hash algorithm to the password value before writing it to the entry, so it is computationally difficult to recover the plaintext version of the password from the stored value. |
|
Self service group creation |
Authenticated Example.com users can create self service groups. |
|
Self service group deletion |
The authenticated owner of a self service group can delete the group. |
|
Self service group registration |
Authenticated Example.com users can sign themselves up as members of self service groups. |
|
User-Visible Monitor Attributes |
Authenticated users can read monitoring information if they have the monitor read privilege. Modification or removal may affect applications. |
|
User-visible operational attributes |
Anonymous and authenticated users can read attributes that identify entries and that contain information about modifications to entries. |
|
User-Visible Root DSE Operational Attributes |
Anonymous and authenticated users can read attributes that describe what the server supports. Modification or removal may affect applications. |
|
User-Visible Schema Operational Attributes |
Authenticated users can read LDAP schema definitions. Modification or removal may affect applications. |
|
Install DS for AM CTS
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the appropriate
setup
command with the--profile am-cts
option.Installation settings depend on AM token expiration and session capability requirements. Letting DS expire tokens is efficient, but affects sending AM notifications about session expiration and timeouts to AM policy agents.
-
For details about AM token expiration options, refer to Manage expired CTS tokens.
-
For details about the mechanism DS uses to expire tokens, refer to Entry expiration.
-
AM reaper manages all token expiration (AM default):
$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --monitorUserPassword str0ngMon1torPa55word \ --hostname ds.example.com \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --profile am-cts \ --set am-cts/amCtsAdminPassword:5up35tr0ng \ --acceptLicense
-
AM reaper manages only SESSION token expiration:
$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --monitorUserPassword str0ngMon1torPa55word \ --hostname ds.example.com \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --profile am-cts \ --set am-cts/amCtsAdminPassword:5up35tr0ng \ --set am-cts/tokenExpirationPolicy:am-sessions-only \ --acceptLicense
-
DS manages all token expiration:
$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --monitorUserPassword str0ngMon1torPa55word \ --hostname ds.example.com \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --profile am-cts \ --set am-cts/amCtsAdminPassword:5up35tr0ng \ --set am-cts/tokenExpirationPolicy:ds \ --acceptLicense
In the preceding example commands:
-
The deployment ID for installing the server is stored in the environment variable
DEPLOYMENT_ID
. Install all servers in the same deployment with the same deployment ID and deployment ID password. For details, read Deployment IDs. -
The service account to use in AM when connecting to DS has:
-
Bind DN:
uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens
. -
Password: The password you set with
am-cts/amCtsAdminPassword
.
-
-
The base DN for AM CTS tokens is
ou=famrecords,ou=openam-session,ou=tokens
.AM and IDM expect exclusive access to the data in each setup profile. Keep the data separate by using distinct base DNs and domains for each setup profile. Don’t accidentally mix the data by choosing a base DN under another base DN.
-
The
am-cts
profile excludes the base DN from change number indexing.
For the full list of profiles and parameters, refer to Default setup profiles.
-
-
Finish configuring the server before you start it.
For a list of optional steps at this stage, refer to Install DS for custom cases.
-
Start the server:
$ /path/to/opendj/bin/start-ds
Install DS for AM configuration
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the
setup
command with the--profile am-config
option:$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --monitorUserPassword str0ngMon1torPa55word \ --hostname ds.example.com \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --profile am-config \ --set am-config/amConfigAdminPassword:5up35tr0ng \ --acceptLicense
-
The deployment ID for installing the server is stored in the environment variable
DEPLOYMENT_ID
. Install all servers in the same deployment with the same deployment ID and deployment ID password. For details, read Deployment IDs. -
The service account to use in AM when connecting to DS has:
-
Bind DN:
uid=am-config,ou=admins,ou=am-config
. -
Password: The password you set with
am-config/amConfigAdminPassword
.
-
-
The base DN for AM configuration data is
ou=am-config
.AM and IDM expect exclusive access to the data in each setup profile. Keep the data separate by using distinct base DNs and domains for each setup profile. Don’t accidentally mix the data by choosing a base DN under another base DN.
For the full list of profiles and parameters, refer to Default setup profiles.
-
-
Finish configuring the server before you start it.
For a list of optional steps at this stage, refer to Install DS for custom cases.
-
Start the server:
$ /path/to/opendj/bin/start-ds
Install DS for platform identities
Use this profile when setting up DS as an identity repository and user data store for AM alone or shared with IDM in a Ping Identity Platform deployment. It includes the additional LDAP schema and indexes required to store the identities:
When AM and IDM share multiple DS replicas for identities:
|
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the
setup
command with the--profile am-identity-store
option:$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --monitorUserPassword str0ngMon1torPa55word \ --hostname ds.example.com \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --profile am-identity-store \ --set am-identity-store/amIdentityStoreAdminPassword:5up35tr0ng \ --acceptLicense
-
The deployment ID for installing the server is stored in the environment variable
DEPLOYMENT_ID
. Install all servers in the same deployment with the same deployment ID and deployment ID password. For details, read Deployment IDs. -
The service account to use in AM when connecting to DS has:
-
Bind DN:
uid=am-identity-bind-account,ou=admins,ou=identities
. -
Password: The password you set with
am-identity-store/amIdentityStoreAdminPassword
.
-
-
The base DN for AM identities is
ou=identities
.AM and IDM expect exclusive access to the data in each setup profile. Keep the data separate by using distinct base DNs and domains for each setup profile. Don’t accidentally mix the data by choosing a base DN under another base DN.
For the full list of profiles and parameters, refer to Default setup profiles.
-
-
Finish configuring the server before you start it.
For a list of optional steps at this stage, refer to Install DS for custom cases.
-
Start the server:
$ /path/to/opendj/bin/start-ds
Install DS as an IDM repository
When IDM uses multiple DS replicas, configure IDM for failover. |
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the
setup
command with the--profile idm-repo
option:$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --hostname localhost \ --adminConnectorPort 34444 \ --ldapPort 31389 \ --enableStartTls \ --profile idm-repo \ --set idm-repo/domain:forgerock.com \ --acceptLicense
-
The deployment ID for installing the server is stored in the environment variable
DEPLOYMENT_ID
. Install all servers in the same deployment with the same deployment ID and deployment ID password. For details, read Deployment IDs. -
The administrative account to use in IDM when connecting to DS has:
-
Bind DN: The DN set with the
--rootUserDN
option. -
Password: The password set with the
--rootUserPassword
option.
-
-
The base DN for IDM data is
dc=openidm,dc=forgerock,dc=com
.AM and IDM expect exclusive access to the data in each setup profile. Keep the data separate by using distinct base DNs and domains for each setup profile. Don’t accidentally mix the data by choosing a base DN under another base DN.
-
IDM requires change number indexing with the default settings.
For the full list of profiles and parameters, refer to Default setup profiles.
-
-
Finish configuring the server before you start it.
For a list of optional steps at this stage, refer to Install DS for custom cases.
-
If all access to DS goes through IDM, IDM manages password policy.
In this case, relax the default password policy settings:
$ dsconfig \ set-password-policy-prop \ --policy-name "Default Password Policy" \ --reset password-validator \ --offline \ --no-prompt $ dsconfig \ set-password-policy-prop \ --policy-name "Root Password Policy" \ --reset password-validator \ --offline \ --no-prompt
-
Start the server:
$ /path/to/opendj/bin/start-ds
Install DS for user data
This profile includes indexes for inetOrgPerson
entries.
It is not intended for deployments with AM or IDM identities.
It does not include the additional LDAP schema and indexes required to store AM identities. To set up a user data store for AM or for sharing between AM and IDM, refer to Install DS for platform identities instead.
To import generated sample user data, refer to Install DS for evaluation instead:
-
Before proceeding, install the server files.
For details, refer to Unpack files.
-
Run the
setup
command with the--profile ds-user-data
option:$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --monitorUserPassword str0ngMon1torPa55word \ --hostname ds.example.com \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --profile ds-user-data \ --set ds-user-data/baseDn:dc=example,dc=com \ --set ds-user-data/ldifFile:/tmp/user-data.ldif \ --acceptLicense
In this example, the
/tmp/user-data.ldif
file contains the user data entries to import. This is just a placeholder. When you run the command, replace it with your LDIF file containing your own user data.-
The deployment ID for installing the server is stored in the environment variable
DEPLOYMENT_ID
. Install all servers in the same deployment with the same deployment ID and deployment ID password. For details, read Deployment IDs. -
The data is stored in the
userData
backend.
For the full list of profiles and parameters, refer to Default setup profiles.
-
-
Finish configuring the server before you start it.
For a list of optional steps at this stage, refer to Install DS for custom cases.
-
Start the server:
$ /path/to/opendj/bin/start-ds
This setup profile creates the following indexes for user data:
Index | Approx. | Equality | Ordering | Presence | Substring | Entry Limit |
---|---|---|---|---|---|---|
|
- |
- |
- |
Yes |
- |
4000 |
|
- |
Yes |
- |
- |
Yes |
4000 |
|
Non-configurable internal index |
|||||
|
- |
Yes |
- |
- |
- |
4000 |
|
- |
Yes |
- |
- |
- |
4000 |
|
- |
Yes |
- |
- |
- |
4000 |
|
- |
- |
Yes |
- |
- |
4000 |
|
- |
Yes |
- |
- |
- |
4000 |
|
- |
Yes |
- |
- |
Yes |
4000 |
|
Non-configurable internal index |
|||||
|
Non-configurable internal index |
|||||
|
- |
Yes |
- |
- |
Yes |
4000 |
|
- |
Yes |
- |
- |
- |
4000 |
|
- |
Yes |
- |
- |
- |
4000 |
|
- |
Yes |
- |
- |
Yes |
4000 |
|
- |
Yes |
- |
- |
Yes |
4000 |
|
- |
Yes |
- |
- |
- |
4000 |
|
- |
Yes |
- |
- |
- |
4000 |
Install DS for custom cases
Follow these steps to install a DS replica with your own custom configuration:
-
Before proceeding, install the server files.
For details, refer to Unpack files.
-
Run the
setup
command with any required setup profiles. -
Finish configuring the server.
Perform any of the following optional steps before starting the server.
Use the
--offline
option with commands instead of the credentials and connection information shown in many examples:-
Add custom syntaxes and matching rules.
For examples, refer to Custom indexes for JSON.
-
Configure password storage.
For details, refer to Configure password policies.
Take care to configure the password policy import plugin as well. For details on the settings, refer to Password Policy Import Plugin.
-
Add custom LDAP schema.
For details, refer to LDAP schema.
-
Configure one or more backends for your data.
For details, refer to Create a backend. When you create the backend, unless you choose not to replicate the data, follow each step of the procedure, adapting the example commands for offline use:
-
Configure the new backend using the
dsconfig create-backend
as shown. -
Verify that replication is enabled using the
dsconfig get-synchronization-provider-prop
command as shown. -
Let the server replicate the base DN of the new backend, using the
dsconfig create-replication-domain
command as shown to configure the replication domain. -
If you have existing data for the backend, make appropriate plans to initialize replication, as described in Manual initialization.
-
-
Configure indexes for the backends you configured.
For details, refer to Indexes.
-
Make sure the server has the shared master key for encrypted data and backups.
If you set up the servers with a known deployment ID and password, you have nothing to do.
If you do not know the deployment ID and password, refer to Replace deployment IDs.
-
Initialize replication.
For example, import the data from LDIF, or restore the data from backup.
For details, refer to Manual initialization, Import LDIF, or Restore.
-
-
Start the server:
$ /path/to/opendj/bin/start-ds
When you start the server, it generates initial state identifiers (generation IDs) for its replicated base DNs. If you perform the above configuration steps on replicas separately after starting them, their generation IDs can be out of sync.
When generation IDs do not match on different replicas for a particular base DN, DS must assume that the replicas do not have the same data. As a result, replication cannot proceed. To fix the mismatch of this replica’s generation IDs with other replicas, stop the server and clear all replication data:
$ /path/to/opendj/bin/stop-ds
$ /path/to/opendj/bin/dsrepl clear-changelog
Clearing the changelog before all the changes have been sent to other replication servers can cause you to lose data. Use the |
Complete any further configuration necessary while the replica is stopped to align it with other replicas.
When you start the replica again with the start-ds
command,
other replication servers update it with the data needed to resume replication.
For details on replication, refer to Replication and the related pages.
Install a directory proxy
Directory proxy servers forward LDAP requests for user data to remote directory servers. Proxy servers make it possible to provide a single point of access to a directory service, and to hide implementation details from client applications.
Check compatibility
DS proxy servers connect to remote LDAP directory servers using proxied authorization.
The proxied authorization control (OID: 2.16.840.1.113730.3.4.18
) is defined by
RFC 4370
Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control.
If the LDAP directory server does not support proxied authorization,
it cannot be used with DS directory proxy server.
The following list of LDAP servers do not support proxied authorization, and so, do not work with DS directory proxy server:
-
Microsoft Active Directory
-
Oracle Internet Directory
The following list of LDAP servers support proxied authorization according to their documentation. Ping Identity does not test all servers listed:
-
PingDS
-
PingDirectory
-
ApacheDS
-
NetIQ eDirectory
-
OpenDJ
-
OpenLDAP
-
Oracle Directory Server Enterprise Edition
-
Red Hat Directory Server
If your LDAP server does not appear in the lists above, check its documentation
regarding support for proxied authorization.
Alternatively, check the list of supportedControl
values on the server’s root DSE.
Try DS directory proxy
Before installing DS directory proxy server in production, or with a non-DS directory server, try it on your computer.
The following examples demonstrate DS directory proxy server forwarding LDAP requests to two DS replicas on your computer. This demonstration includes the following high-level tasks:
-
Install two DS directory server replicas as proxied servers.
-
Set up the DS directory proxy server to forward requests to the DS directory servers.
-
Send LDAP requests to the DS directory proxy server, and observe the results.
The deployment ID for installing the server is stored in the environment variable DEPLOYMENT_ID
.
Install all servers in the same deployment with the same deployment ID and deployment ID password.
For details, read Deployment IDs.
The DS directory proxy server does not have backup files or directory data to encrypt and decrypt. But it does open secure connections to the remote directory servers, and so must trust the certificates that the remote directory servers present to negotiate TLS. By default, DS deployments use TLS keys and a CA generated from the deployment ID and deployment ID password. This is the same deployment ID and password used to configure the DS directory servers. Therefore, use the same deployment ID and password when configuring DS directory proxy servers, so they can trust the directory server certificates. |
Install two DS directory server replicas with the evaluation and proxied server profiles:
# Unpack server files:
unzip -q ~/Downloads/DS-7.5.1.zip -d /tmp
# Copy server files before setting up each replica:
mkdir /path/to/opendj && cp -r /tmp/opendj/* /path/to/opendj
mkdir /path/to/replica && cp -r /tmp/opendj/* /path/to/replica
# Set up the servers as replicas of each other
# with StartTLS support for the proxy connections:
/path/to/opendj/setup \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword password \
--hostname localhost \
--ldapPort 11389 \
--enableStartTls \
--ldapsPort 11636 \
--adminConnectorPort 14444 \
--rootUserDN uid=admin \
--rootUserPassword password \
--profile ds-evaluation \
--profile ds-proxied-server \
--set ds-proxied-server/baseDn:dc=example,dc=com \
--replicationPort 18989 \
--bootstrapReplicationServer localhost:28989 \
--acceptLicense \
--start \
--quiet
/path/to/replica/setup \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword password \
--hostname localhost \
--ldapPort 21389 \
--enableStartTls \
--ldapsPort 21636 \
--adminConnectorPort 24444 \
--rootUserDN uid=admin \
--rootUserPassword password \
--profile ds-evaluation \
--profile ds-proxied-server \
--set ds-proxied-server/baseDn:dc=example,dc=com \
--replicationPort 28989 \
--bootstrapReplicationServer localhost:18989 \
--acceptLicense \
--start \
--quiet
# Update PATH to include DS tools:
export PATH=/path/to/opendj/bin:${PATH}
Notice that the examples apply two setup profiles to each replica:
-
The DS evaluation setup profile adds sample Example.com data.
For details, refer to Install DS for evaluation.
-
The DS proxied server setup profile adds a service account for the proxy server, and sets ACIs to grant the account permission to use proxied authorization. The proxy authenticates to the directory servers with its certificate, whose subject DN is
CN=DS, O=ForgeRock.com
.For details, refer to Install DS for use with DS proxy.
Set up a directory proxy server to forward requests to the replicas:
# Copy server files before setting up the proxy:
mkdir /path/to/proxy && cp -r /tmp/opendj/* /path/to/proxy
# Set up the proxy server to access the replicas:
/path/to/proxy/setup \
--serverId proxy \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword password \
--rootUserDN uid=admin \
--rootUserPassword password \
--hostname localhost \
--ldapPort 1389 \
--enableStartTls \
--ldapsPort 1636 \
--adminConnectorPort 4444 \
--profile ds-proxy-server \
--set ds-proxy-server/bootstrapReplicationServer:"localhost:14444" \
--set ds-proxy-server/bootstrapReplicationServer:"localhost:24444" \
--set ds-proxy-server/rsConnectionSecurity:start-tls \
--set ds-proxy-server/certNickname:ssl-key-pair \
--set ds-proxy-server/keyManagerProvider:PKCS12 \
--set ds-proxy-server/trustManagerProvider:PKCS12 \
--start \
--acceptLicense
# Grant access to data through the proxy server:
dsconfig \
create-global-access-control-policy \
--hostname localhost \
--port 4444 \
--bindDN uid=admin \
--bindPassword password \
--policy-name "Authenticated access to example.com data" \
--set authentication-required:true \
--set request-target-dn-equal-to:"dc=example,dc=com" \
--set request-target-dn-equal-to:"**,dc=example,dc=com" \
--set permission:read \
--set permission:write \
--set allowed-attribute:"*" \
--set allowed-attribute:isMemberOf \
--set allowed-attribute-exception:authPassword \
--set allowed-attribute-exception:userPassword \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--no-prompt
As you set up only DS servers which all use the same default schema, there is no need to manually align the proxy LDAP schema with the directory server schema.
Send LDAP requests to the DS directory proxy server, and observe the results.
The following example searches the directory through the proxy:
$ ldapsearch \
--hostname localhost \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=kvaughan,ou=people,dc=example,dc=com \
--bindPassword bribery \
--baseDN "ou=people,dc=example,dc=com" \
"(|(cn=Babs Jensen)(cn=Sam Carter))" \
cn
dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
dn: uid=scarter,ou=People,dc=example,dc=com
cn: Sam Carter
The following example modifies directory data through the proxy:
$ ldapmodify \
--hostname localhost \
--port 1636 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=bjensen,ou=people,dc=example,dc=com \
--bindPassword hifalutin << EOF
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: description
description: Modified by Babs Jensen
EOF
# MODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com
Notice that the bind DNs and passwords are those of the users in the remote directory service.
For more background on each high-level task, read the rest of this page.
Create a service account
When preparing to use DS directory proxy servers with directory servers that are not DS servers, create a service account for the proxy to connect to the non-DS remote directory service.
The directory proxy server binds with this service account, and then forwards LDAP requests on behalf of other users.
For DS directory servers, use the proxied server setup profile if possible. For details, refer to Install DS for use with DS proxy.
The service account must have the following on all remote directory servers:
-
The same bind credentials.
If possible, use mutual TLS to authenticate the proxy user with the backend servers.
-
The right to perform proxied authorization.
Make sure the LDAP servers support proxied authorization (control OID:
2.16.840.1.113730.3.4.18
).For details, refer to RFC 4370, Lightweight Directory Access Protocol (LDAP) Proxied Authorization Control.
-
When using a replication discovery mechanism with remote DS directory servers, the service account requires the
config-read
andmonitor-read
privileges for the service discovery mechanism. It requires theproxied-auth
privilege and an ACI to perform proxied authorization.
The following listing shows an example service account that you could use with DS replicas. Adapt the account as necessary for your directory service:
dn: uid=proxy
objectClass: top
objectClass: account
objectClass: ds-certificate-user
uid: proxy
ds-certificate-subject-dn: CN=DS, O=ForgeRock.com
ds-privilege-name: config-read
ds-privilege-name: monitor-read
ds-privilege-name: proxied-auth
aci: (targetcontrol="ProxiedAuth")
(version 3.0; acl "Allow proxied authorization";
allow(read) userdn="ldap:///uid=proxy";)
Set up a directory proxy
The deployment ID for installing the server is stored in the environment variable DEPLOYMENT_ID
.
Install all servers in the same deployment with the same deployment ID and deployment ID password.
For details, read Deployment IDs.
Proxy to DS servers
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the
setup --profile ds-proxy-server
command.The command is located where you installed the files,
/path/to/opendj/setup
:The following example sets up a directory proxy server that discovers remote servers based on the DS replication topology. It works with replicas set up using the
ds-proxied-server
setup profile.This feature works only with DS servers. If the remote LDAP servers in your deployment are not DS servers, refer to Proxy to non-DS servers.
This proxy forwards all requests to public naming contexts of remote servers. Generally, this means requests targeting user data, as opposed to the proxy’s configuration, schema, or monitoring statistics:
$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --hostname ds.example.com \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --adminConnectorPort 4444 \ --profile ds-proxy-server \ --set ds-proxy-server/bootstrapReplicationServer:"rs.example.com:4444" \ --set ds-proxy-server/rsConnectionSecurity:start-tls \ --set ds-proxy-server/certNickname:ssl-key-pair \ --set ds-proxy-server/keyManagerProvider:PKCS12 \ --set ds-proxy-server/trustManagerProvider:PKCS12 \ --start \ --acceptLicense
This example uses mutual TLS with a certificate generated with a deployment ID and password. Adjust the security settings as required for your deployment.
Proxy to non-DS servers
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the
setup --profile ds-proxy-server
command.The command is located where you installed the files,
/path/to/opendj/setup
:The following example sets up a directory proxy server that has a static list of remote servers to connect to. It forwards only requests targeting
dc=example,dc=com
:# Initially configure the server with a fake replication service discovery mechanism: $ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --hostname ds.example.com \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --adminConnectorPort 4444 \ --profile ds-proxy-server \ --set ds-proxy-server/bootstrapReplicationServer:"fake-rs.example.com:4444" \ --set ds-proxy-server/rsConnectionSecurity:start-tls \ --start \ --acceptLicense # Create a static service discovery mechanism: $ dsconfig \ create-service-discovery-mechanism \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ --mechanism-name "Static Service Discovery Mechanism" \ --type static \ --set primary-server:local1.example.com:636 \ --set primary-server:local2.example.com:636 \ --set secondary-server:remote1.example.com:636 \ --set secondary-server:remote2.example.com:636 \ --set ssl-cert-nickname:ssl-key-pair \ --set key-manager-provider:PKCS12 \ --set trust-manager-provider:"JVM Trust Manager" \ --set use-ssl:true \ --set use-sasl-external:true \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt # Replace the fake replication service discovery mechanism with the static one: $ dsconfig \ set-backend-prop \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ --backend-name proxyRoot \ --set shard:"Static Service Discovery Mechanism" \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
This example uses mutual TLS with a certificate generated with a deployment ID and password. Adjust the security settings as required for your deployment.
Configure access control
-
Explicitly grant appropriate access to remote data.
The following example grants authenticated users access to data under
dc=example,dc=com
:$ dsconfig \ create-global-access-control-policy \ --hostname localhost \ --port 4444 \ --bindDN uid=admin \ --bindPassword str0ngAdm1nPa55word \ --policy-name "Authenticated access to example.com data" \ --set authentication-required:true \ --set request-target-dn-equal-to:"dc=example,dc=com" \ --set request-target-dn-equal-to:"**,dc=example,dc=com" \ --set permission:read \ --set permission:write \ --set allowed-attribute:"*" \ --set allowed-attribute:isMemberOf \ --set allowed-attribute-exception:authPassword \ --set allowed-attribute-exception:userPassword \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --no-prompt
DS proxy servers do not use ACIs for access control. Instead, they use global access control policies. By default, the access rights are configured the same as the default settings for a directory server. You no doubt need to adapt these policies for your deployment. For additional examples, refer to Access control.
-
Make sure the backend directory servers are properly prepared, as described Create a service account.
For more background on LDAP proxy features, refer to LDAP proxy.
Default global policies
Access control rules are defined using individual access control policy entries. A user’s access is defined as the union of all access control rules that apply to that user. In other words, an individual access control rule can only grant additional access and can not remove rights granted by another rule. This approach results in an access control policy which is easier to understand and audit, since all rules can be understood in isolation.
Policy | Settings |
---|---|
Anonymous extended operation and control access |
|
Authenticated extended operation and control access |
|
Schema access |
|
Root DSE access |
|
Monitor access |
|
Align LDAP schema
Directory servers can reject LDAP change requests that do not comply with LDAP schema. LDAP client applications read LDAP schema definitions from directory servers to determine in advance whether a change request complies with LDAP schema.
When an LDAP client requests LDAP schema from the proxy, the proxy returns its LDAP schema. Ideally, the LDAP schema definitions on the proxy match the LDAP schema definitions on the remote directory servers. Otherwise, client applications might check their requests against the proxy’s LDAP schema, and yet still have their requests fail with schema violations when the proxy forwards a request to a directory server.
If, after installation, the LDAP schema definitions on the directory servers and the proxy server differ, align the LDAP schema of the proxy server with the LDAP schema of the remote directory servers.
For more information, refer to LDAP schema. Schema definitions on a non-DS remote directory server might require translation from another format before you add them on DS directory proxy servers.
Troubleshooting
Common errors with DS directory proxy server installations include the following:
- 49 (Invalid Credentials)
-
When LDAP bind requests through the proxy invariably result in an invalid credentials error, but bind requests to the directory server with the same credentials do not, the problem lies with the proxy service account.
The proxy service account must allow bind requests to the directory server. The following example demonstrates a request sent directly to a directory server. The command makes a bind request and then a search request. The directory server is set up according to the instructions in Try DS directory proxy:
$ ldapsearch \ --hostname localhost \ --port 1636 \ --useSsl \ --usePkcs12TrustStore /path/to/opendj/config/keystore \ --trustStorePassword:file /path/to/opendj/config/keystore.pin \ --bindDN uid=kvaughan,ou=people,dc=example,dc=com \ --bindPassword bribery \ --baseDN "ou=people,dc=example,dc=com" \ "(|(cn=Babs Jensen)(cn=Sam Carter))" \ cn dn: uid=bjensen,ou=People,dc=example,dc=com cn: Barbara Jensen cn: Babs Jensen dn: uid=scarter,ou=People,dc=example,dc=com cn: Sam Carter
Start with the filtered directory server access log,
logs/filtered-ldap-access.audit.json
, to debug bind failures. - 123 (Authorization Denied)
-
Make sure that access control on the remote LDAP servers allows the proxy service account to use the proxied authorization control.
Proxied authorization does not allow operations on remote LDAP servers as the directory superuser (
uid=admin
). Do not connect as directory superuser when trying to access a directory server through the proxy. For administrative requests on remote LDAP servers, access the servers directly. This includes monitoring requests.It is possible to configure proxied authorization so that an anonymous user (no bind DN, no bind password) can make a request through the proxy server to the remote directory server. Avoid doing this, however, as it is less secure.
Many applications perform some operations anonymously, such as reading the root DSE or LDAP schema. These operations are in fact requests to the proxy, not forwarded to remote LDAP servers. For applications to receive an appropriate response for LDAP schema requests, align LDAP schema on the proxy with LDAP schema on the remote LDAP servers as described above.
Install DS for use with DS proxy
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the
setup
command with the--profile ds-proxied-server
option.The example shows the profile used with the evaluation profile. Add this profile to the list so proxy servers can access other profiles' data:
$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword str0ngAdm1nPa55word \ --monitorUserPassword str0ngMon1torPa55word \ --hostname ds.example.com \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer rs1.example.com:8989 \ --bootstrapReplicationServer rs2.example.com:8989 \ --profile ds-evaluation \ --profile ds-proxied-server \ --set ds-proxied-server/baseDn:dc=example,dc=com \ --acceptLicense
-
The deployment ID for installing the server is stored in the environment variable
DEPLOYMENT_ID
. Install all servers in the same deployment with the same deployment ID and deployment ID password. For details, read Deployment IDs. -
The account the DS proxy can use to connect to DS replicas has:
-
Bind DN: The DN from the
--set ds-proxied-server/proxyUserDn
option.Default:
uid=proxy
. -
Certificate subject DN: The DN from the
--set ds-proxied-server/proxyUserCertificateSubjectDn
option.Default:
CN=DS, O=ForgeRock.com
. -
Access to use proxied authorization in the base DNs specified by the multivalued
--set ds-proxied-server/baseDn
option.If you do not specify any values for
ds-proxied-server/baseDn
, the proxy user can perform operations with any account as authorization identity. This includes administrator accounts.To understand what this means, read Proxied authorization.
-
-
The DS proxy server binds using certificate-based authentication with the SASL EXTERNAL mechanism.
Make sure that the DS replicas' truststores lets them trust the proxy’s certificate.
-
The DS proxy server uses proxied authorization to perform operations on the DS replicas.
The authorization identity for the operations must have appropriate access to the data on the DS replicas.
For the full list of profiles and parameters, refer to Default setup profiles.
-
-
Finish configuring the server before you start it.
For a list of optional steps at this stage, refer to Install DS for custom cases.
-
Start the server:
$ /path/to/opendj/bin/start-ds
Install standalone servers (advanced)
This information applies to advanced deployments. |
Standalone replication servers have no application data backends. They store only changes to directory data. They are dedicated to transmitting replication messages, and to maintaining a replication change log.
Standalone directory servers store replicated copies of application data. These replicas send updates to and receive updates from replication servers. They connect to one replication server at a time, and do not maintain a replication change log.
Each replication server in a deployment connects to all other replication servers. The total number of replication connections, Totalconn, increases like the number of replication servers squared. Large deployments that span slow, high-latency links can benefit from having fewer replication servers.
Totalconn = (NRS * (NRS-1))/2 + NDS
Here, NRS is the number of replication servers (standalone or running in a directory server), and NDS is the number of standalone directory servers.
A deployment with only a few standalone replication servers and many standalone directory servers, significantly limits the number of connections for replication over slow links:
The deployment ID for installing the server is stored in the environment variable DEPLOYMENT_ID
.
Install all servers in the same deployment with the same deployment ID and deployment ID password.
For details, read Deployment IDs.
Set up standalone replication servers
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Set up a server as a standalone replication server:
$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword password \ --hostname rs-only.example.com \ --adminConnectorPort 4444 \ --replicationPort 8989 \ --bootstrapReplicationServer rs-only.example.com:8989 \ --bootstrapReplicationServer rs-only2.example.com:8989 \ --acceptLicense
The standalone replication server has no application data.
It does have LDAP schema and changelog data. If you plan to add any additional schema to the replicas as part of the setup process, also add the schema to this server before starting it.
-
Start the server:
$ /path/to/opendj/bin/start-ds
-
Repeat the previous steps on additional systems until you have sufficient replication servers to meet your availability requirements.
To ensure availability, add at least one additional replication server per location. The following example adds a second standalone replication server:
$ /path/to/opendj/setup \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword password \ --hostname rs-only2.example.com \ --adminConnectorPort 4444 \ --replicationPort 8989 \ --bootstrapReplicationServer rs-only.example.com:8989 \ --bootstrapReplicationServer rs-only2.example.com:8989 \ --acceptLicense
The standalone replication servers use each other as bootstrap servers to discover other servers in the deployment.
Set up standalone directory servers
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Set up the server as a directory server.
Notice that the
--bootstrapReplicationServer
references the replication servers set up according to the steps in Set up standalone replication servers.The
--replicationPort
option is not used, because this is a standalone directory server:$ /path/to/opendj/setup \ --serverId evaluation-only \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --rootUserDN uid=admin \ --rootUserPassword password \ --adminConnectorPort 4444 \ --hostname ds-only.example.com \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --bootstrapReplicationServer rs-only.example.com:8989 \ --bootstrapReplicationServer rs-only2.example.com:8989 \ --profile ds-evaluation \ --acceptLicense
-
Finish configuring the server before you start it.
For a list of optional steps at this stage, refer to Install DS for custom cases.
-
Start the server:
$ /path/to/opendj/bin/start-ds
-
Repeat the previous steps on additional systems until you have sufficient directory servers to meet your availability and performance requirements.
To ensure availability, add at least one additional directory server per location.
Use your own cryptographic keys
When you set up a DS server with your own keys for PKI, account for the following points:
|
The setup
command has options to simplify setting up a server with existing keys:
For… | Use… |
---|---|
Keystores containing server key pairs |
|
Truststores containing trusted CA or self-signed certificates |
|
Important features to be aware of:
-
If the keystore file that holds the server key pair protects the server key with a password, that password must match the password for the entire store.
DS does not support separate keystore and key passwords in keystore files.
-
If you are using an HSM, also read PKCS#11 hardware security module.
-
If you are using PEM format keys, read PEM format keys.
-
CAs can optionally set X.509 key usage extensions in server certificates.
If the CA does set key usage extensions, make sure it includes at least the required settings:
Protocol X.509 extension Required settings HTTP
KeyUsage
digitalSignature
keyEncipherment
ExtendedKeyUsage
serverAuth
(TLS server authentication)LDAP
KeyUsage
digitalSignature
keyEncipherment
ExtendedKeyUsage
serverAuth
(TLS server authentication)Replication
KeyUsage
digitalSignature
keyEncipherment
ExtendedKeyUsage
clientAuth
(TLS client authentication)(1)
serverAuth
(TLS server authentication)
1.3.6.1.4.1.36733.2.1.10.1
(for Trusted replicas (advanced))(1) Replication requires both TLS server and TLS client roles.
Follow steps similar to these to install a DS replica with existing cryptographic keys:
-
Before proceeding, install the server files.
For details, refer to Unpack files. -
Run the
setup
command with the appropriate options.The following example uses a PKCS#12 keystore file with the server’s key pair, and a PKCS#12 truststore file with the CA’s certificate.
This example installs the server with the evaluation setup profile. Adapt the command for your use:
# Set up a directory server for evaluation using existing keys: $ /path/to/opendj/setup \ --serverId evaluation-only \ --deploymentId $DEPLOYMENT_ID \ --deploymentIdPassword password \ --usePkcs12TrustStore /path/to/truststore \ --trustStorePassword password \ --certNickname ssl-key-pair \ --usePkcs12KeyStore /path/to/keystore \ --keyStorePassword password \ --rootUserDN uid=admin \ --rootUserPassword password \ --monitorUserPassword password \ --hostname localhost \ --adminConnectorPort 4444 \ --ldapPort 1389 \ --enableStartTls \ --ldapsPort 1636 \ --httpsPort 8443 \ --replicationPort 8989 \ --bootstrapReplicationServer localhost:8989 \ --profile ds-evaluation \ --acceptLicense
-
Finish configuring the server.
-
Start the server:
$ /path/to/opendj/bin/start-ds
When you set up the server to use existing keystore files, the server configuration directly references those files. If you read the server configuration, you find that a Key Manager Provider references the keystore, and that a Trust Manager Provider references the truststore.
If you provide keystore and truststore passwords as strings,
the setup
command records them in files in the opendj/config
directory.
For details on using variables instead, refer to Property value substitution.
Install an HDAP gateway
The DS HDAP gateway web application translates HTTP requests in LDAP requests:
The HDAP gateway functions as a web application in a web application container. It runs independently of the LDAPv3 directory service. The LDAPv3 directory service must support proxied authorization. In particular, this means you can use the HDAP gateway with current and previous versions of DS.
Installation
-
Review the requirements for installation to verify the HDAP gateway supports your web application container.
-
Deploy the .war file according to the instructions for your web application container; for example:
$ cp DS-hdap-servlet-7.5.1.war /path/to/tomcat/webapps/
If you use Wildfly, you must unzip the .war file into the deployment directory.
-
Edit the configuration in the deployed gateway web application:
WEB-INF/classes/config.json
-
This file defines how the HDAP gateway connects to and interacts with LDAP directory servers.
At minimum, set the directory server hostnames, port numbers, and proxy user credentials. The proxy user LDAP account performs proxied authorization. In a DS directory server set up for evaluation, the account with simple bind credentials
cn=My App,ou=Apps,dc=example,dc=com
andpassword
can act as a proxy user.When connecting to the remote directory service over LDAPS or LDAP and StartTLS (recommended), configure the gateway client-side trust manager to trust the server certificates. For help, refer to the examples showing how to trust DS server certificates.
WEB-INF/classes/logging.properties
-
This file defines logging properties when you run the gateway in Apache Tomcat.
-
(Optional) Adjust the log level.
At the default log level of
INFO
, the HDAP gateway logs messages about HTTP requests. For log level definitions, refer to java.util.logging.Level.If the HDAP gateway runs in Apache Tomcat, edit the
logging.properties
file. Otherwise, set the log level as described in the container documentation. -
(Recommended) Configure the web application container to use HTTPS for secure connections to the gateway.
Refer to the container documentation for details.
-
Restart the HDAP gateway or the web application container.
The gateway reloads its configuration.
-
Verify the directory service is up and the gateway connects correctly.
Verification
Install and configure the HDAP gateway before following these steps:
-
Set up a DS directory server for evaluation.
-
Read Babs Jensen’s resource through the gateway.
If necessary, adjust the protocol (
https
), port (8443
), and base path (/hdap
) for your configuration:$ curl \ --user dc=com/dc=example/ou=People/uid=bjensen:hifalutin \ 'https://localhost:8443/hdap/dc=com/dc=example/ou=People/uid=bjensen?_fields=cn&_prettyPrint=true' { "_id" : "dc=com/dc=example/ou=People/uid=bjensen", "_rev" : "<revision>", "cn" : [ "Barbara Jensen", "Babs Jensen" ] }
You have demonstrated the HDAP gateway works as expected.
Install a DSML gateway
The DSML gateway web application translates each HTTP request into one or more LDAP requests.
The interface stability of this feature is Deprecated. |
The translation depends on the DSML protocol. For authentication, you must configure how HTTP user IDs map to LDAP identities.
The DSML gateway functions as a web application in a web application container.
The DSML gateway runs independently of the directory service.
You configure the gateway to access a directory service by editing parameters in the gateway configuration file,
WEB-INF/web.xml
:
-
Deploy the .war file according to the instructions for your web application container.
-
Edit
WEB-INF/web.xml
to ensure the parameters are correct.For details, refer to Configure DSML access.
-
Configure your web application container to use HTTPS for secure connections to the gateway.
Refer to your web application container documentation for details.
-
Restart the web application according to the instructions for your web application container.
Configure DSML access
Directory Services Markup Language (DSML) client access is implemented as a servlet web application.
You edit the WEB-INF/web.xml
file after deploying the web application.
The list of DSML configuration parameters are the following:
ldap.host
-
The hostname of the underlying directory service.
Default:
localhost
ldap.port
-
The LDAP port number of the underlying directory service.
Default:
389
ldap.userdn
-
Optional parameter specifying the DN to bind to the underlying directory service.
Default: anonymous bind
ldap.userpassword
-
Optional parameter specifying the password to bind to the underlying directory service.
Default: anonymous bind
ldap.authzidtypeisid
-
Use this parameter to set up the DSML gateway to do HTTP Basic Access Authentication, given the appropriate mapping between the user ID, and the user’s entry in the directory.
This takes a boolean parameter specifying whether the HTTP Authorization header field’s Basic credentials in the request hold a plain ID, rather than a DN.
If set to
true
, the gateway performs an LDAP SASL bind using SASL plain, enabled by default in DS servers to look for an exact match between auid
in the server, and the plain ID from the header.In other words, if the plain ID is
bjensen
, then the bind DN isuid=bjensen,ou=people,dc=example,dc=com
.Configure DS identity mappers as necessary to use a different attribute than
uid
. For background information, refer to Identity mappers.Default:
false
ldap.usessl
-
Whether
ldap.port
uses LDAPS.Default:
false
ldap.usestarttls
-
Whether to use StartTLS when connecting to
ldap.port
.Default:
false
ldap.trustall
-
Whether to blindly trust all server certificates when using LDAPS or StartTLS.
Default:
false
ldap.truststore.path
-
The truststore used to verify server certificates when using LDAPS or StartTLS.
Required when using LDAPS or StartTLS and
ldap.trustall
isfalse
. ldap.truststore.password
-
The password to read the truststore.
Required when using a truststore with a password.
For initial testing purposes, try JXplorer,
where the DSML Service is: /webapp-dir/DSMLServlet
.
The webapp-dir
refers to the name of the directory holding the DSML .war
.
Uninstallation
Uninstall .zip
Follow these steps to remove software installed from the cross-platform .zip:
-
Log in as the user who installed and runs the server.
-
Stop the server:
$ /path/to/opendj/bin/stop-ds --quiet
-
Delete the files manually:
$ rm -rf /path/to/opendj
Uninstall the Debian package
When you uninstall the Debian package from the command-line, the server is stopped if it is running:
-
Purge the package from your system:
$ sudo dpkg --purge opendj
-
Remove any remaining server configuration files and directory data:
$ sudo rm -rf /opt/opendj
Uninstall the RPM package
When you uninstall the RPM package from the command-line, the server is stopped if it is running:
-
Remove the package from your system:
root# rpm -e opendj
-
Remove the server configuration files and any directory data:
$ sudo rm -rf /opt/opendj
Uninstall the Windows MSI
When you uninstall the files installed from the Windows installer package, only the installed files are removed.
File layout
DS software installs and creates the following files and directories. The following table is not meant to be exhaustive.
File or directory | Description |
---|---|
|
Directory intended for local backup data. |
|
Windows command-line tools. |
|
Linux command-line tools. |
|
Backend for replication changelog data. |
|
Directory added to the server classpath, permitting individual classes to be patched. |
|
(Optionally) immutable server configuration files. |
|
Templates for configuring external Common Audit event handlers. |
|
LDIF representation of current DS server configuration. |
|
Keystore and password ( |
|
Templates for use with the |
|
Default directory for backend database files. For details, refer to Data storage. |
|
Directory for additional .jar files used by your custom plugins. If the instance path is not the same as the binaries,
copy additional files into the |
|
Working directory used when importing LDIF data. |
|
Directory for saving LDIF export files. |
|
License information. |
|
Scripts and libraries shipped with DS servers. |
|
Directory for custom plugins. |
|
Lock files that prevent more than one process from using the same backend. |
|
Access, errors, and audit logs. |
|
Contains the process ID for a running server. |
|
DS splash logo. |
|
About DS servers. |
|
Samples for use with DS servers, such as:
|
|
Linux setup tool. |
|
Windows setup tool. |
|
Templates for setting up a server instance. |
|
Profile scripts to configure directory servers for specific use cases. |
|
Linux upgrade tool. |
|
Windows upgrade tool. |
|
Files the DS server writes to during operation. Do not modify or move files in the |
|
Snapshots of the main server configuration file, The server writes a compressed snapshot file when the configuration is changed. |
|
The most recent version of the main server configuration file that the server successfully started with. |
(1) The samples are provided on an "as is" basis. Ping Identity does not guarantee the individual success developers may have in implementing the samples on their development platforms or in production configurations.
For details about how to try the samples, refer to the accompanying README.md
files.