How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I change the hostname in DS 5.x and 6.x?

Last updated Apr 8, 2021

The purpose of this article is to provide information on changing the hostname for a DS server. This article covers both replicated and non-replicated servers.


3 readers recommend this article

Overview

DS 7 introduces several improvements, which makes changing the hostname much simpler. See Maintenance Guide › Move a Server for an example.

In earlier versions, you should follow the steps in the Changing the hostname (pre-DS 7) section. 

Changing the hostname (Pre-DS 7)

This process uses the following example server hostnames:

  • Original hostname: dsA.example.com
  • New hostname: dsB.example.com
  • Hostname of another replicated server: dsZ.example.com

To change the server hostname:

  1. Direct client applications to other servers.
  2. Prevent the server from accepting updates from client applications using the following command: $ ./dsconfig set-global-configuration-prop --port 4444 --hostname dsA.example.com --bindDN "cn=Directory Manager" --bindPassword password --set writability-mode:internal-only --trustAll --no-prompt
  3. If the server is replicated, disable replication using the dsreplication command: $ ./dsreplication unconfigure --unconfigureAll --hostname dsA.example.com --port 4444 --adminUID admin --adminPassword password --trustAll --no-prompt
  4. Change the hostname details in the /etc/hosts file and/or on the DNS.
  5. Change the server-fqdn in the DIGEST-MD5 entry using the following command: $ ./dsconfig set-sasl-mechanism-handler-prop --handler-name DIGEST-MD5 --port 4444 --hostname dsA.example.com --bindDN "cn=Directory Manager" --bindPassword password --set server-fqdn:dsB.example.com --trustAll
  6. Restart DS: $ ./stop-ds $ ./start-ds
  7. Regenerate all self-signed certificates. See Administration Guide › Preparing For Secure Communications and Administration Guide › Changing Server Certificates for further information.
  8. Restart DS: $ ./stop-ds $ ./start-ds
  9. If the server was replicated, enable replication on the new server using the dsreplication command:$ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 dsZ.example.com --port1 4444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 8989 --host2 dsB.example.com --port2 4444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 8989 --trustAll --no-prompt
  10. If the server was replicated, initialize the new server to ensure it has all the changes that have occurred since you disabled replication: $ ./dsreplication initialize --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostSource dsZ.example.com --portSource 4444 --hostDestination dsB.example.com --portDestination 4444 --trustAll --no-prompt
  11. Re-enable the server to accept updates from client applications using the following command: $ ./dsconfig set-global-configuration-prop --port 4444 --hostname dsA.example.com --bindDN "cn=Directory Manager" --bindPassword password --set writability-mode:enabled --trustAll --no-prompt

How does DS resolve the hostname?

DS picks up what the JVM or operating system has recorded for the FQDN. If you have not changed the hostname correctly, you may see the following error (referencing the original hostname):

[27/Feb/2017:15:33:59 -0800] category=JVM severity=NOTICE msgID=18 msg=JVM Host: Unknown (java.net.UnknownHostException: dsA.example.com: dsA.example.com: Name or service not known), running Linux 2.6.32-573.3.1.el6.x86_64 amd64, 4017881088 bytes physical memory size, number of processors available 4

You can confirm that the JVM or operating system is broadcasting the wrong FQDN using the hostname command:

$ hostname dsA.example.com

On a Linux® system, you can correct the FQDN being broadcast by updating the /etc/sysconfig/network file with the correct FQDN and restarting your system. Upon running the hostname command again, you should see the new hostname, which means DS will use the correct one and you should no longer see this error.

See Also

Installing and Administering DS

Administration Guide › Moving Servers

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.