--- title: Before you upgrade in place description: New releases can bring updated requirements and incompatible changes. Ignoring these changes when upgrading can break your deployment and cause downtime. component: pingds version: 8.1 page_id: pingds:upgrade-guide:before-you-upgrade-in-place canonical_url: https://docs.pingidentity.com/pingds/8.1/upgrade-guide/before-you-upgrade-in-place.html revdate: 2026-04-21T12:00:00Z keywords: ["Compatibility", "LDAP", "Upgrade"] section_ids: supported_java: Supported Java upgrade-generated-cas: CAs from deployment IDs required_credentials: Required credentials back_up_first: Back up first disable_windows_service: Disable Windows service next_steps: Next steps --- # Before you upgrade in place | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | New releases can bring updated requirements and incompatible changes. Ignoring these changes when upgrading can break your deployment and cause downtime.Make sure you review the [release notes](https://docs.pingidentity.com/pingds/release-notes/index.html) carefully and take all appropriate actions when upgrading to a new release, especially in a production environment. | Fulfill these requirements before upgrading PingDS software, especially before upgrading the software in a production environment. ## Supported Java | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | * Always use a JVM with the latest security fixes. * Make sure you have a supported Java environment installed on the system. If your default Java environment isn't appropriate, use one of the following solutions: * Edit the `default.java-home` setting in the `opendj/config/java.properties` file. * Set `DS_JAVA_HOME` to the path to the correct Java environment. * Set `DS_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 and refer to [CAs from deployment IDs](#upgrade-generated-cas). | 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 - Oracle Java - Red Hat OpenJDKPing Identity tests most extensively with AdoptOpenJDK/Eclipse Temurin.Use the HotSpot JVM if possible. | 25 | TLS cipher support depends solely on the JVM. Learn more in [TLS settings](../security-guide/connections.html#tls-protocols-cipher-suites). ## CAs from deployment IDs Due to a change to the Java platform between versions 11 and 17, the key pairs you generate with the `dskeymgr` and `setup` commands using Java 11 are incompatible with keys generated using Java 17 and later. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Running DS servers with incompatible Java versions is a problem when you use deployment ID-based CA certificates.If you [use your own CA](../install-guide/setup-own-keys.html), not one derived from a deployment ID, skip this section. | 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. Find troubleshooting suggestions in [Overcome incompatible Java versions when adding new servers](../maintenance-guide/troubleshooting.html#troubleshoot-incompatible-java-versions-add-server). ## 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 windows-service.bat --disableService ``` After upgrade, enable the server as a Windows service again. ## Next steps * [icon: check-square-o, set=fa]Perform [these steps](before-you-upgrade-in-place.html) before you upgrade * [icon: square-o, set=fa]*Upgrade each:* * [icon: square-o, set=fa][Directory server](upgrade-ds.html) * [icon: square-o, set=fa][Directory proxy](upgrade-proxy.html) * [icon: square-o, set=fa][Replication server](upgrade-rs.html) * [icon: square-o, set=fa][HDAP gateway](upgrade-rest.html) * [icon: square-o, set=fa]Perform [these steps](after-you-upgrade-in-place.html) after you upgrade