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 ForgeRock® 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.4.2
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.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.2.0
The ds-evaluation:7.2.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
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 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.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.