--- title: Plan the upgrade description: How much you must do to upgrade AM software depends on the magnitude of the differences between the version you currently use and the new version: component: pingam version: 7.3 page_id: pingam:upgrade-guide:upgrade-planning canonical_url: https://docs.pingidentity.com/pingam/8.1/upgrade/upgrade-planning.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Upgrade"] section_ids: plan-upgrade-downtime: Route around servers during downtime pre-upgrade-backup: Back up the deployment review-REST-API-versions: Review REST API versions before upgrading pre-upgrade-certificates: Review Directory Services certificates before upgrading pre-upgrade-customization: Customize before upgrading post-upgrade-rollback: Plan for rollback testing-upgrade: Upgrade in a test environment first --- # Plan the upgrade How much you must do to upgrade AM software depends on the magnitude of the differences between the version you currently use and the new version: * Maintenance releases have a limited effect on current functionality but contain necessary bug and security fixes. Keep up to date with maintenance releases, as the fixes are important and the risk of affecting service is minimal. * When upgrading to a new major or minor release, always plan and test the changes before carrying out the upgrade in production. Make sure you read the release notes for intervening versions with care, identifying any changes likely to affect your deployment, and then plan accordingly. Review the following best practices before you upgrade AM: * [Route around servers during downtime](#plan-upgrade-downtime) * [Back up the deployment](#pre-upgrade-backup) * [Review REST API versions before upgrading](#review-REST-API-versions) * [Review Directory Services certificates before upgrading](#pre-upgrade-certificates) * [Customize before upgrading](#pre-upgrade-customization) * [Plan for rollback](#post-upgrade-rollback) * [Upgrade in a test environment first](#testing-upgrade) ## Route around servers during downtime Upgrading servers takes at least one of your AM sites down while the server configurations are being brought up to date with the newer version. Plan for this site to be down, routing client applications to another site until the upgrade process is complete and you have validated the result. Make sure client application owners are well aware of the change, and let them know what to expect. If you only have a single AM site, make sure the downtime happens in a low usage window, and make sure you let client application owners plan accordingly. During an upgrade you must restrict access to the AM console: The Upgrade Wizard page does not require authorization; any user with access to the AM admin UI immediately after you deploy the new WAR file can therefore initiate the upgrade process. ## Back up the deployment Always back up your deployment before you upgrade, as you must be able to roll back should something go wrong during the upgrade process. * Backing up your configuration as described in [Back up configurations](../maintenance-guide/backup-restore.html) is good for production environments. * In preparation for upgrading AM servers and their configurations, also take LDIF backups of the configuration store data in the directory servers. If possible, stop servers before upgrading and take a file system backup of the deployed servers and also of their configuration directories as well. This can make it easier to roll back from a failed upgrade. For example, if you deploy AM server in Apache Tomcat under `/openam`, you might take a file system backup of the following directories for each AM server. * `/path/to/tomcat/webapps/openam/` * `~/openam/` * `~/.openamcfg/` * When upgrading tools, keep copies of any tools scripts that you have edited for your deployment. Also back up any trust stores used to connect securely. * Record any custom advanced server properties configured under Configure > Server Defaults > Advanced or Deployment > Servers > *Server Name* > Advanced in the AM admin UI. These properties are lost during the upgrade and will need to be added again after the upgrade is complete. ## Review REST API versions before upgrading Upgrading AM may update the default API version of several AM endpoints. After an upgrade, your applications may experience issues connecting to endpoints if they do not specify API version information in REST calls. By default, an upgraded AM instance responds to REST calls that do not specify version information with the oldest version available for the endpoint. However, the oldest supported version may not be the one required by the application, as API versions become deprecated or unsupported. To avoid version conflicts between application calls and REST endpoint APIs, consider specifying the protocol and resource version required by the application in the `Accept-API-Version` header when making requests to REST endpoints. For more information, see [Specifying REST API Versions](../REST-guide/rest-api-versioning.html#rest-api-explicit-version). | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Starting in version 6, AM includes a CSRF protection filter that is enabled by default. REST requests other than GET, HEAD, and OPTIONS made to endpoints under the `json/` root will return 403 Forbidden messages unless one of the `X-Requested-With` or `Accept-API-Version` headers are added to it.For more information, see [Protect against CSRF attacks](../security-guide/rest-CSRF.html). | You can configure AM's default REST API behavior. For more information, see [Configuring the Default REST API Version](../REST-guide/rest-api-versioning.html#configure-default-version). ## Review Directory Services certificates before upgrading Before upgrading, review that the certificates used to establish secure connections between AM and the DS stores. If the FQDN value from the `subject` field of a non-wildcard certificate does not match the FQDN obtained from DNS for the DS instance, AM will not be able to establish a secure connection with DS. Additionally, if the DS instance responds to multiple FQDNs, they must be specified in the certificate as well. This step is critical for the configuration store. If AM cannot establish communication with the configuration store, it will fail to start up. For more information about setting up DS server certificates, see [Key Management](https://docs.pingidentity.com/pingds/7.3/security-guide/key-management.html) in the DS documentation. ## Customize before upgrading Prepare a `.war` file that contains any customizations you require. Customizations include any changes you have made to the AM server installation, such as the following: * Custom plugin and extensions, for example: * Custom authentication modules. * Custom authentication nodes. * Post-authentication plugins. * Custom SAML 2.0 attribute mappers. * Custom OAuth 2.0 scope validators. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | New functionality oftentimes changes the samples provided with AM.Do not copy custom plugins or extensions from a previous version of AM to the `.war` file.You must customize the samples of the version you are upgrading to before adding them to the `.war` file. For example, download the custom scope validator sample of the version you are upgrading to, customize it, recompile it, and then add the resulting `.jar` file to the `.war` file.Failure to use the new version's samples as the base for your customizations may result in unexpected behavior. | * Customized JSPs, redesigned login or service pages, additional CSS and visual content, and modified authentication module callback files. * Any changes to AM classes or APIs. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Recompile any custom implementations you have created with each release of AM, as the method signature or imports for supported and evolving APIs can change in each version. | * Any changes or additional Java class libraries (such as .jar files in `WEB-INF/lib` ). ## Plan for rollback Sometimes even a well-planned upgrade operation fails to go smoothly. In such cases, you need a plan to roll back smoothly to the pre-upgrade version. For AM servers, you can roll back by restoring from file system backup. If you use an external configuration directory service, restore the old configuration from LDIF before restarting the old servers. For more information, see [Back up configurations](../maintenance-guide/backup-restore.html). ## Upgrade in a test environment first Always try upgrading AM in a test environment before applying the upgrade in your production environment. This will help you gauge the amount of work required without affecting your production environment, and will help smooth out unforeseen problems.