PingDS 7.5.1

Add new servers

When upgrading by adding new DS 7 and later servers to a DS 6.5 or earlier deployment, add the new directory servers or replication servers as described on this page.

If all the servers are DS 7 or later and use the new security model based on deployment IDs, not cn=admin data, then skip these instructions. Install the new servers as described in the pages on Installation, and rebuild indexes as necessary.

  • Set up replication before upgrade. Do not set up replication for the first time between servers of different versions.

  • The new server you add must first connect to an existing replica that is a directory server, not a standalone replication server.

  • Newer directory servers update LDAP schema definitions to add support for new features. The newer schema definitions are not all compatible with older servers.

  1. Install and set up a new server, but do not start it, yet.

    Because replication is now configured at setup time, you may need to create the new server with some specific arguments. The following table indicates which arguments are needed for which kind of server:

    New server is a…​ Use this replication setup option

    Combined DS/RS

    --replicationPort port

    Standalone DS

    N/A

    Standalone RS

    --replicationPort port

    • Do not use the setup --bootstrapReplicationServer option. In a later step of this procedure, you will use the dsrepl add-local-server-to-pre-7-0-topology command. That command configures the bootstrap replication server settings for the new server based on the existing deployment.

    • Do not use the setup --start option. In a later step of this procedure, you will start the server.

    For details about setup options, refer to Setup hints, and many of the examples that use the setup command.

  2. Configure the new server settings to be compatible with the settings of the existing servers.

    Examples of incompatible default settings include:

    • Password storage schemes not available in earlier versions.

    • String-based server IDs. Server IDs were limited to numbers between 1 and 65535.

      Remove leading 0 (zero) characters when setting a numeric server ID. DS servers classify a server ID with a leading 0 as a string, not a number.

    • String-based group IDs. Group IDs were also limited to numbers.

    • TLS protocols and cipher suites.

    For changes in the release, refer to Incompatible changes. If the existing servers run a release older than 6.5, refer to similar pages in the previous release notes.

  3. Configure the new server as a replica of an existing server that is a directory server, and not a standalone replication server:

    $ dsrepl \
 add-local-server-to-pre-7-0-topology \
 --hostname pre-7-ds.example.com \
 --port 4444 \
 --bindDn "cn=admin,cn=Administrators,cn=admin data" \
 --bindPassword password \
 --baseDn dc=example,dc=com \
 --trustAll \
 --no-prompt

    The existing server in this example is a directory server, as suggested by the ds in the hostname. The dsrepl add-local-server-to-pre-7-0-topology command does not support connecting to a standalone replication server.

    The command configures the new server, discovering the replication servers in the deployment, and setting the bootstrap replication servers.

    The command also generates one or more dsrepl initialize commands. Copy those commands, and add required credentials for use when initializing the new server.

    In the example command shown here:

    • The --bindDn and --bindPassword options reflect either the UID and password of the existing servers' global replication administrator, or the DN and password of any user with sufficient access to act as global administrator on all servers.

    • The insecure --trustAll option is used to simplify this procedure.

      To avoid using this option, add the remote server’s CA or signing certificate to the new server’s keystore, and use the appropriate keystore options.

  4. Start the new server.

  5. Initialize the new server:

    New server is a…​ Initialize these base DNs

    Combined DS/RS

    cn=admin data, cn=schema, all directory data DNs

    Standalone DS

    cn=admin data, cn=schema, all directory data DNs

    Standalone RS

    cn=admin data

    • For cn=admin data and cn=schema, use the dsrepl initialize command(s) from the previous step.

    • For other base DNs, if initializing over the network is appropriate—​for example, because there is little directory data under the base DN compared to available network bandwidth—​use the dsrepl initialize command.

      Otherwise, initialize from LDIF or from backup taken on another new server of the same version. For details, refer to Manual initialization.

      Test the initialization process to make sure you understand the duration and ramifications of the chosen initialization method.

      Use the results to make an evidence-based decision on whether to use backup/restore or export/import instead of online initialization.

  6. Align the change number indexing settings on the new servers to match the same settings on the existing servers.

  7. Rebuild "degraded" mail indexes for the change to the mail attribute schema definition to allow UTF-8 characters.

    The definitions for DS 7.3 and later allow UTF-8, whereas earlier versions allow only ASCII. The change does not affect the data, but does affect mail indexes.

    For details, refer to Automate index rebuilds.

  8. Rebuild indexes as necessary for changes to schema definitions for the RFC 2703bis Internet-Draft, An Approach for Using LDAP as a Network Information Service.

    The definitions for DS 7.2 and later align with those of the latest Internet-Draft. The change does not affect the data, but does affect indexes for the following attributes:

    • automountInformation

    • automountKey

    • automountMapName

    • gecos

    • ipHostNumber

    • ipNetworkNumber

    • memberNisNetGroup

    • memberUid

    • nisMapEntry

    • nisNetgroupTriple

    Use the new schema Use the old schema

    When you add a new server, it replicates the new schema.

    Rebuild "degraded" indexes on existing, older servers.

    For details, on rebuilding degraded indexes, refer to Automate index rebuilds.

    Before upgrading, save a copy of the schema file, db/schema/04-rfc2307bis.ldif, from an existing server.

    After upgrading:

    • Replace the newer schema file with your saved copy.

    • Rebuild "degraded" indexes on the newer servers.

  9. If necessary, add the deprecated /admin and /api (REST to LDAP) endpoints to the server configuration:

    # /admin
$ dsconfig \
 create-http-endpoint \
 --endpoint-name /admin \
 --type admin-endpoint \
 --set authorization-mechanism:"HTTP Basic" \
 --set enabled:true \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

# /api (REST to LDAP)
$ dsconfig \
 create-http-endpoint \
 --endpoint-name /api \
 --type rest2ldap-endpoint \
 --set authorization-mechanism:"HTTP Basic" \
 --set config-directory:config/rest2ldap/endpoints/api \
 --set enabled:true \
 --hostname localhost \
 --port 4444 \
 --bindDN uid=admin \
 --bindPassword password \
 --usePkcs12TrustStore /path/to/opendj/config/keystore \
 --trustStorePassword:file /path/to/opendj/config/keystore.pin \
 --no-prompt

Next steps

Copyright © 2010-2024 ForgeRock, all rights reserved.