Configuration reference
About this reference
This reference describes server configuration settings that you can view and edit with the dsconfig
command.
The dsconfig
command is the primary tool for managing the server configuration,
which follows an object-oriented configuration model.
Each configuration object has its own properties.
Configuration objects can be related to each other by inheritance and by reference.
The server configuration model exposes a wide range of configurable features.
As a consequence, the dsconfig
command has many subcommands.
Subcommands exist to create, list, and delete configuration objects, and to get and set properties of configuration objects. Their names reflect these five actions:
-
create-
object -
list-
objects -
delete-
object -
get-
object-prop
-
set-
object-prop
Each configuration object has a user-friendly name, such as Connection Handler
.
Subcommand names use lower-case, hyphenated versions of the friendly names, as in create-connection-handler
.
Subcommands
Objects
Duration syntax
Durations are specified with positive integers and unit specifiers.
Unit specifiers include the following:
-
ms
: milliseconds -
s
: seconds -
m
: minutes -
h
: hours -
d
: days -
w
: weeks
A duration of 1 week is specified as 1w
.
A duration of 1 week, 1 day, 1 hour, 1 minute, and 1 second is specified as 1w1d1h1m1s
.
Whitespace surrounding the value and the unit specifier is not significant.
For example, "5d"
is equivalent to " 5 d "
.
Not all properties taking a duration allow all unit specifiers. For example, milliseconds are not allowed if durations smaller than one second are not permitted.
Some properties limit minimum or maximum durations.
An unlimited duration is specified using unlimited
(recommended for readability) or -1
.
Size syntax
Sizes are specified with non-negative integers and unit specifiers, which are not case-sensitive.
Unit specifiers include the following:
-
b
,bytes
-
kb
,kilobytes
(x1000) -
kib
,kibibytes
(x1024) -
mb
,megabytes
(x1000x1000) -
mib
,mebibytes
(x1024x1024) -
gb
,gigabytes
(x1000x1000x1000) -
gib
,gibibytes
(x1024x1024x1024) -
tb
,terabytes
(x1000x1000x1000x1000) -
tib
,tebibytes
(x1024x1024x1024x1024) -
unlimited
,-1
(if allowed, explicitly set no upper limit)
For example, you can specify a size of 1,000,000 bytes as 1MB
.
To specify a size of 1,048,576 bytes, use 1MiB
or 1 mib
, for example.
Whitespace surrounding the value and the unit specifier is not significant.
For example, "5gb"
is equivalent to " 5gb "
.
Some properties limit minimum or maximum sizes.
Property value substitution
Property value substitution enables you to achieve the following:
-
Define a configuration that is specific to a single instance.
For example, set the location of the keystore on a particular host.
-
Define a configuration whose parameters vary between different environments.
For example, change hostnames for test, development, and production environments.
Disable certain capabilities on specific servers. For example, disable a database backend and its replication agreement for one set of replicas while enabling it on another set of replicas. This makes it possible to use the same configuration for environments with different data sets.
Property value substitution uses configuration expressions to introduce variables into the server configuration. You set configuration expressions as the values of configuration properties. The effective property values can be evaluated in a number of ways.
Scope of configuration expressions
DS servers only resolve configuration expressions in the DS servers do not resolve configuration expressions anywhere else. DS servers resolve expressions at startup to determine the configuration. DS commands that read the configuration in offline mode also resolve expressions at startup. When you use expressions in the configuration, you must make their values available before starting the server and also when running such commands. |
Configuration expressions share their syntax and underlying implementation with other platform software. Configuration expressions have the following characteristics:
-
To distinguish them from static values, expression tokens are preceded by an ampersand and enclosed in braces.
For example:
&{listen.port}
. The expression token in the example islisten.port
. The.
serves as the separator character. -
You can use a default value in an expression by including it after a vertical bar following the token.
For example, the following expression sets the default listen port value to 1389:
&{listen.port|1389}
. -
A configuration property can include a mix of static values and expressions.
For example, if
hostname
is set todirectory
,&{hostname}.example.com
evaluates todirectory.example.com
. -
You can define nested properties (that is, a property definition within another property definition).
For example, if
listen.port
is set to&{port.prefix}389
, andport.prefix
is set to2
,&{listen.port}
evaluates to2389
. -
You can read the value of an expression token from a file.
For example, if the plaintext password is stored in
/path/to/password.txt
, the following expression resolves to the plaintext password:&{file:/path/to/password.txt}
.You specify the file either by its absolute path, or by a path relative to the DS instance directory. In other words, if the DS instance directory is
/path/to/opendj
, then/path/to/opendj/config/keystore
andconfig/keystore
reference the same file.
DS servers define the following expression tokens by default. You can use these in expressions without explicitly setting their values beforehand:
ds.instance.dir
-
The file system directory holding the instance files required to run an instance of a server.
By default, the files are co-located with the product tools, libraries, and configuration files. You can change the location by using the
setup --instancePath
option.This evaluates to a directory, such as
/path/to/my-instance
. ds.install.dir
-
The file system directory where the server files are installed.
This evaluates to a directory, such as
/path/to/opendj
.
Expression evaluation and order of precedence
You must define expression values before starting the DS server that uses them.
When evaluated, an expression must return the appropriate type for the configuration property.
For example, the listen-port
property takes an integer.
If you set it using an expression, the result of the evaluated expression must be an integer.
If the type is wrong, the server fails to start due to a syntax error.
If the expression cannot be resolved, and there is no default value in the configuration expression, DS also fails to start.
Expression resolvers evaluate expression tokens to literal values.
Expression resolvers get values from the following sources:
Environment variables
You set an environment variable to hold the value.
For example: export LISTEN_PORT=1389
.
The environment variable name must be composed of uppercase characters and underscores. The name maps to the expression token as follows:
-
Uppercase characters are lower cased.
-
Underscores,
_
, are replaced with.
characters.
In other words, the value of LISTEN_PORT
replaces &{listen.port}
in the server configuration.
Java system properties
You set a Java system property to hold the value.
Java system property names must match expression tokens exactly.
In other words, the value of the listen.port
system property replaces &{listen.port}
in the server configuration.
Java system properties can be set in a number of ways.
One way of setting system properties for DS servers is
to pass them through the OPENDJ_JAVA_ARGS
environment variable.
For example: export OPENDJ_JAVA_ARGS="-Dlisten.port=1389"
.
Expressions files
You set a key in a .json
or .properties
file to hold the value.
This optional mechanism is set using the DS_ENVCONFIG_DIRS
environment variable,
or the ds.envconfig.dirs
Java system property.
Keys in .properties
files must match expression tokens exactly.
In other words, the value of the listen.port
key replaces &{listen.port}
in the server configuration.
The following example properties file sets the listen port:
listen.port=1389
JSON expression files can contain nested objects. JSON field names map to expression tokens as follows:
-
The JSON path name matches the expression token.
-
The
.
character serves as the JSON path separator character.
The following example JSON file sets the listen address and listen port:
{
"listen": {
"address": "192.168.0.10",
"port": "1389"
}
}
In other words, the value of the listen/port
field replaces &{listen.port}
in the server configuration.
In order to use expression files, set the environment variable, DS_ENVCONFIG_DIRS
, or the Java system property,
ds.envconfig.dirs
, to a comma-separated list of the directories containing the expression files.
The following constraints apply when using expression files:
-
Although DS browses the directories in the specified order, within a directory DS scans the files in a non-deterministic order.
-
DS reads all files with
.json
and.properties
extensions. -
DS does not scan subdirectories.
-
Do not define the same configuration token more than once in a file, as you cannot know in advance which value will be used.
-
You cannot define the same configuration token in more than one file in a single directory. If the same token occurs in more than one file in a single directory, an error occurs.
-
If the same token occurs once in several files which are located in different directories, the first value that DS reads is used.
The preceding list reflects the order of precedence:
-
Environment variables override system properties, default token settings, and settings in any expression files.
-
System properties override default token settings, and any settings in expression files.
-
If
DS_ENVCONFIG_DIRS
ords.envconfig.dirs
is set, then the server uses settings found in expression files. -
Default token settings (
ds.config.dir
,ds.instance.dir
,ds.install.dir
).
For an embedded DS server, it is possible to change the expression resolvers, in the server configuration.
Use multivalued expressions
A single expression token can evaluate to multiple property values. Such expressions are useful with multivalued properties.
For example, suppose you choose to set a connection handler’s ssl-cipher-suite
property.
Instead of listing cipher suites individually, you use an ssl.cipher.suites
token that takes multiple values.
The following example commands set the token value in the environment, stop the server, use the expression in the LDAP connection handler configuration while the server is offline, and then start the server again:
$ export SSL_CIPHER_SUITES=\
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,\
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,\
TLS_EMPTY_RENEGOTIATION_INFO_SCSV
$ stop-ds --quiet
$ dsconfig \
set-connection-handler-prop \
--offline \
--handler-name LDAPS \
--add ssl-protocol:TLSv1.2 \
--add ssl-cipher-suite:'&{ssl.cipher.suites}' \
--no-prompt
$ start-ds --quiet
Multiple values are separated by commas in environment variables, system properties, and properties files. They are formatted as arrays in JSON files.
Use one of the following alternatives to set the value of the ssl.cipher.suites
token.
In each case, when the server evaluates &{ssl.cipher.suites}
, the result is the following property values:
ssl-cipher-suite: TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
ssl-cipher-suite: TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
ssl-cipher-suite: TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
ssl-cipher-suite: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
ssl-cipher-suite: TLS_EMPTY_RENEGOTIATION_INFO_SCSV
Environment variable
export SSL_CIPHER_SUITES=\
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,\
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,\
TLS_EMPTY_RENEGOTIATION_INFO_SCSV
System property
export OPENDJ_JAVA_ARGS="-Dssl.cipher.suites=\
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,\
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,\
TLS_EMPTY_RENEGOTIATION_INFO_SCSV"
Properties file
ssl.cipher.suites=\
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,\
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,\
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,\
TLS_EMPTY_RENEGOTIATION_INFO_SCSV
JSON file
{
"ssl.cipher.suites": [
"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_EMPTY_RENEGOTIATION_INFO_SCSV"
]
}
Alternative JSON file that sets ssl.protocol
as well:
{
"ssl": {
"protocol": "TLSv1.2",
"cipher.suites": [
"TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_EMPTY_RENEGOTIATION_INFO_SCSV"
]
}
}
In order to fully use the settings in this file,
you would have to change the example to include the additional expression:
--add ssl-protocol:'&{ssl.protocol}'
.
Debug expressions
You can debug configuration expressions.
Create a debug target for org.forgerock.config.resolvers
.
The following example demonstrates the process:
$ dsconfig \
create-debug-target \
--hostname localhost \
--port 4444 \
--bindDN uid=admin \
--bindPassword password \
--publisher-name "File-Based Debug Logger" \
--type generic \
--target-name org.forgerock.config.resolvers \
--set enabled:true \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--no-prompt
$ dsconfig \
set-log-publisher-prop \
--hostname localhost \
--port 4444 \
--bindDN uid=admin \
--bindPassword password \
--publisher-name "File-Based Debug Logger" \
--set enabled:true \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePassword:file /path/to/opendj/config/keystore.pin \
--no-prompt
$ stop-ds --restart --quiet
When the server starts, it logs debugging messages for configuration expressions. Do not leave debug logging enabled in production systems.