--- title: Before you upgrade description: Fulfill these requirements before upgrading Directory Services software, especially before upgrading the software in a production environment. Also refer to the requirements listed in release notes. component: pingds version: 7.4 page_id: pingds:upgrade-guide:before-you-upgrade canonical_url: https://docs.pingidentity.com/pingds/8.1/upgrade-guide/before-you-upgrade.html llms_txt: https://docs.pingidentity.com/pingds/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2025-08-21T16:45:32Z keywords: ["Compatibility", "LDAP", "Upgrade"] superseded_by: https://docs.pingidentity.com/pingds/8.1/upgrade-guide/before-you-upgrade.html section_ids: upgrade-java: Supported Java upgrade-credentials: Required credentials upgrade-backup: Back up first upgrade-disable-windows-service: Disable Windows service --- # Before you upgrade Fulfill these requirements before upgrading Directory Services software, especially before upgrading the software in a production environment. Also refer to the requirements listed in [release notes](https://docs.pingidentity.com/pingds/release-notes/requirements.html). ## Supported Java | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * Always use a JVM with the latest security fixes. * Make sure you have a required Java environment installed on the system. If your default Java environment is not appropriate, use one of the following solutions: * Edit the `default.java-home` setting in the `opendj/config/java.properties` file. * Set `OPENDJ_JAVA_HOME` to the path to the correct Java environment. * Set `OPENDJ_JAVA_BIN` to the absolute path of the `java` command. * When running the `dskeymgr` and `setup` commands, use the same Java environment everywhere in the deployment. Due to a change in Java APIs, the same DS deployment ID generates different CA key pairs with Java 11 and Java 17. Using different Java versions is a problem if you use deployment ID-based CA certificates. Replication breaks, for example, when you use the `setup` command for a new server with a more recent version of Java than was used to set up existing servers. For details on resolving the issue, refer to [Incompatible Java versions](../maintenance-guide/troubleshooting.html#troubleshoot-incompatible-java-versions). | DS software supports the following Java environments: | Vendor | Versions | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | | OpenJDK, including OpenJDK-based distributions:- AdoptOpenJDK/Eclipse Temurin Java Development Kit (Adoptium) - Amazon Corretto - Azul Zulu - Red Hat OpenJDKForgeRock tests most extensively with AdoptOpenJDK/Eclipse Temurin.ForgeRock recommends using the HotSpot JVM. | 11(1), 17(2) | | Oracle Java | 11(1), 17(2) | (1) DS requires Java 11.0.6 or later. Earlier Java 11 updates lack required cryptography fixes. * TLS 1.3 with PKCS#11 requires Java 11.0.8 or later. * [Encrypting data at rest](../security-guide/data.html) with the [`ChaCha20` or `ChaCha20-Poly1305` ciphers](https://docs.oracle.com/en/java/javase/11/docs/specs/security/standard-names.html#cipher-algorithm-names) and compatibility with third-party cryptographic tools require Java 11.0.12 or later. (2) DS requires Java 17.0.3 or later. Earlier Java 17 updates lack required cryptography fixes. TLS cipher support depends solely on the JVM. For details, refer to [TLS settings](../security-guide/connections.html#tls-protocols-cipher-suites). ## Required credentials Perform the upgrade procedure as the user who owns the server files. Make sure you have the credentials to run commands as this user. ## Back up first Before upgrading, perform a full file system backup of the current server so that you can revert on failure. Make sure you stop the directory server and *back up the file system directory where the current server is installed*. Backup archives are *not guaranteed to be compatible* across major and minor server releases. *Restore backups only on directory servers of the same major or minor version.* ## Disable Windows service If you are upgrading a server registered as a Windows service, disable the Windows service before upgrade: ```powershell C:\path\to\opendj\bat> windows-service.bat --disableService ``` After upgrade, enable the server as a Windows service again.