Setup Hints

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 setup command.

--instancePath

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.

--serverId

Deployment key

The deployment key is a random string generated by DS software. It is paired with a deployment key password, which is a random string that you choose, and that you must keep secret.

Together, the deployment key and password serve to generate the shared master key that DS servers in the deployment require for protecting shared encryption secrets. By default, the setup command uses them 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 key and password for each server installation.

For details, see Deployment Keys.

--deploymentKey

Deployment key password

This is a random string that you choose, and that you must keep secret. It is paired with the deployment key.

--deploymentKeyPassword[:env|:file]

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 UNIX root user.

The name used in the documentation is the default name: uid=admin.

For additional security in production environments, use a different name.

-D, --rootUserDn

Root user password

The root user authenticates with simple, password-based authentication.

Use a strong password here unless this server is only for evaluation.

-j, --rootUserPassword[:env|:file]

Monitor user DN

The monitor user DN identifies a user with the privilege to read monitoring data (monitor-read).

The account is replicated by default, so use the same DN on each server.

The name used in the documentation is the default name: uid=monitor.

--monitorUserDn

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.

--monitorUserPassword[:env|:file]

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 localhost.

Otherwise, use an FQDN that other hosts can resolve to reach your server, and that matches the FQDN in the server certificate.

-h, --hostname

Administration port

This is the service port used to configure the server and to run tasks.

The port used in the documentation is 4444.

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.

--adminConnectorPort

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 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 setup command is the PIN.

If you do not provide an existing keystore, the setup command generates a deployment key. Keep a secure copy of this key for use when installing other DS servers in your deployment. For details, see Key Management.

Public key security is often misunderstood. Before making security choices for production systems, read Cryptographic Keys.

--useJavaKeyStore
--useJceKeyStore
--usePkcs11KeyStore
--usePkcs12KeyStore
-W, --keyStorePassword[:env|:file]
-N, --certNickname

--useJavaTrustStore
--useJceTrustStore
--usePkcs11TrustStore
--usePkcs12TrustStore
-T, --trustStorePassword[:env|:file]

Start the server

By default, the setup command does not start the server. Finish configuring the server, then use the /path/to/opendj/bin/start-ds command.

If no further configuration is required, use the setup --start option.

-s, --start

LDAP and LDAPS port

The reserved port for LDAP is 389. The reserved port for LDAPS is 636.

Examples in the documentation use 1389 and 1636, which are accessible to non-privileged users.

If you install the server with access to privileged ports (< 1024), and the reserved port is not yet in use, then interactive setup suggests the reserved port number. If the 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.

The LDAP StartTLS extended operation negotiates a secure connection starting on the insecure LDAP port.

-p, --ldapPort
-q, --enableStartTls
-Z, --ldapsPort

HTTP and HTTPS ports

The reserved port for HTTP is 80. The reserved port for HTTPS is 443. The interactive setup initially suggests 8080 and 8443 instead.

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 8443.

When you enable HTTP or HTTPS at setup time, only the administrative endpoints are enabled, /admin/config, /metrics/api, and /metrics/prometheus, allowing applications to configure and monitor the server.

For access to user data in a directory server, see Configure HTTP User APIs.

--httpPort
--httpsPort

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 8989.

-r, --replicationPort

Bootstrap replication servers

Specify bootstrap server host:port pairs, where port is the server’s replication port. The current server contacts the bootstrap servers to discover other servers in the deployment. The host:port pair may represent the current server if it is a 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 -r, --replicationPort option as follows:

--bootstrapReplicationServer

Configure the server for use with other applications

For details, see Setup Profiles.

--profile
--set