--- title: Upgrade description: Learn about upgrade between supported versions of IG in the Ping Identity End of Life (EOL) Software Tracker. Product Support Lifecycle Policy | PingGateway and Agents]. component: pinggateway version: 7.2 page_id: pinggateway:installation-guide:migrate canonical_url: https://docs.pingidentity.com/pinggateway/7.2/installation-guide/migrate.html revdate: 2024-10-08T12:44:32Z section_ids: upgrade-planning: Planning the upgrade upgrade-configuration: Upgrade the IG configuration upgrade-servers: Upgrade IG instances upgrade_a_single_ig_instance: Upgrade a single IG instance upgrade_a_site_with_multiple_ig_instances: Upgrade a site with multiple IG instances upgrade-war-to-zip: Migrate from web container mode to standalone mode session_replication_between_ig_instances: Session replication between IG instances streaming_asynchronous_responses_and_events: Streaming asynchronous responses and events connection_reuse_when_client_certificates_are_used_for_authentication: Connection reuse when client certificates are used for authentication tomcat_configuration: Tomcat configuration --- # Upgrade Learn about upgrade between supported versions of IG in the [Ping Identity End of Life (EOL) Software Tracker](https://support.pingidentity.com/s/article/Ping-Identity-EOL-Tracker#pgateway). Product Support Lifecycle Policy | PingGateway and Agents]. ## Planning the upgrade Major, minor, maintenance, and patch product release levels are defined in [ForgeRock product release levels](../release-notes/stability.html#release-levels). How much you need to do to upgrade IG software depends on the magnitude of the differences between the version you currently use and the new version. Minor, maintenance, and patch releases have a limited effect on current functionality but contain necessary bug and security fixes. Keep up-to-date with maintenance and patch releases because the fixes are important, and the risk of affecting service is minimal. Do these planning tasks **before** you start an upgrade: | Planning task | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Find out what changed | Read the [Release Notes](../release-notes/preface.html) for **all** releases between the version you currently use and the new version. | | Understand the impact | Decide whether you need to change the configuration of your deployment for this release, and evaluate the work involved.Make sure you meet all of the [requirements](../release-notes/before-you-install.html) for the new version. In particular, make sure that you have a recent, supported Java version. | | Plan for server downtime | At least one of your IG servers will be down during upgrade. Plan to route client applications to another server until the upgrade process is complete, and you have validated the result. Make sure client application owners are aware of the change, and let them know what to expect.If you have a single IG server, make sure the downtime happens in a low-usage window, and make sure you let client application owners plan accordingly. | | Back up | The IG configuration is a set of files, including `admin.json`, `config.json`, `logback.xml`, routes, and scripts. Back up the IG configuration and store it in version control, so that you can roll back if something goes wrong.Also back up any tools scripts that you have edited for your deployment, and any trust stores used to connect securely. | | Plan for rollback | Sometimes even a well-planned upgrade fails to go smoothly. In such cases, you need a plan to roll back smoothly to the pre-upgrade version.For IG servers, roll back by restoring a backed-up configuration. | | Prepare a test environment | Before applying the upgrade in your production environment, always try to upgrade IG in a test environment. This will help you gauge the amount of work required, without affecting your production environment, and will help smooth out unforeseen problems.The test environment should resemble your production environment as closely as possible. | ## Upgrade the IG configuration Use the [Release Notes](../release-notes/preface.html) for **all** releases between the version you currently use and the new version, and upgrade your configuration as follows: * Review all [Incompatible changes](../release-notes/changed-functionality.html), and adjust your configuration as necessary. * Switch to the replacement settings in [Deprecation](../release-notes/deprecated-functionality.html). Although deprecated objects continue to work, they add to the notifications in the logs, and are eventually removed. * Check the lists of [Fixes](../release-notes/fixes.html), [Limitations](../release-notes/limitations.html), and [Known issues](../release-notes/known-issues.html), to see if they impact your deployment. * Recompile your Java extensions. The method signature or imports for supported and evolving APIs can change in each version. * Read the [Documentation updates](../release-notes/doc-updates.html) for new examples and information that can help with your configuration. ## Upgrade IG instances For information about the versions that are supported for upgrade, see [Upgrade paths](#supported-upgrades). ### Upgrade a single IG instance 1. Read and act on [Plan the upgrade](#upgrade-planning) and [Upgrade the IG configuration](#upgrade-planning). 2. Back up the IG configuration, and store it in version control so that you can roll back if something goes wrong. 3. Stop IG. 4. Make the new configuration available on the file system, and specify the `IG_INSTANCE_DIR` env variable or `ig.instance.dir` system property to point to them. 5. Restart IG. 6. In a test environment that simulates your production environment, validate that the upgraded service performs as expected with the new configuration. Check the logs for new or unexpected notifications or errors. 7. Allow client application traffic to flow to the upgraded site. ### Upgrade a site with multiple IG instances The most straightforward option when upgrading sites with multiple IG instances is to upgrade in place. One by one, stop, upgrade, and then restart each server individually, leaving the service running during upgrade. ## Migrate from web container mode to standalone mode IG is delivered as a standalone Java executable in a .zip file, as well as in a .war file. Consider these points to migrate from IG in web container mode to IG in standalone mode. ### Session replication between IG instances High-availability of sessions is not supported in standalone mode. ### Streaming asynchronous responses and events In [ClientHandler](../reference/Handlers.html#ClientHandler) and [ReverseProxyHandler](../reference/Handlers.html#ReverseProxyHandler), use only the default mode of `asyncBehavior:non_streaming`; responses are processed when the entity content is entirely available. If the property is set to `streaming`, the setting is ignored. ### Connection reuse when client certificates are used for authentication In [ClientHandler](../reference/Handlers.html#ClientHandler) and [ReverseProxyHandler](../reference/Handlers.html#ReverseProxyHandler), use only the default mode of `stateTrackingEnabled:true`; when a client certificate is used for authentication, connections cannot be reused. If the property is set to `false`, the setting is ignored. ### Tomcat configuration | Feature | Standalone | Tomcat | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Port number | Configure the `connectors` property of [admin.json](../reference/AdminHttpApplication.html). | Configure in the `Connector` element of `/path/to/tomcat/conf/server.xml`:```xml ``` | | HTTPS server-side configuration | Create a keystore, set up secrets, and configure secrets stores, ports, and ServerTlsOptions in [admin.json](../reference/AdminHttpApplication.html).For information, see [Configure IG for HTTPS (server-side) in standalone mode](install-standalone.html#standalone-https). | Create a keystore, and set up the SSL port in the `Connector` element of `/path/to/tomcat/conf/server.xml`.For information, see [Configure IG for HTTPS (server-side) in Tomcat](install-tomcat.html#tomcat-https). | | Session cookie name | Configure the `session` property of [admin.json](../reference/AdminHttpApplication.html). | Configure `WEB-INF/web.xml` when you unpack the IG .war file. | | Access logs | Configure in the Audit framework.For information, see [Auditing your deployment](../maintenance-guide/auditing.html) and [Audit framework](../reference/AuditFramework.html). | Configure with `AccessLogValve`. | | JDBC datasource | Configure with the JdbcDataSource object.For information, see [JdbcDataSource](../reference/MiscellaneousConfigurationObjects.html#JdbcDataSource).For an example, see [Log in with credentials from a database](../gateway-guide/credentials-datasource.html#tutorial-credentials-from-sql). | Configure in the `GlobalNamingResources` element of `/path/to/tomcat/conf/server.xml`. | | Environment variables | Configure in `$HOME/.openig/bin/env.sh`, where `$HOME/.openig` is the instance directory. | Configure in `/path/to/tomcat/bin/setenv.sh`. | | Jar files | Add to `$HOME/.openig/extra`, where `$HOME/.openig` is the instance directory. | Add to to web container classpath; for example `/path/to/tomcat/webapps/ROOT/WEB-INF/lib`. |