--- title: Major upgrade description: Read the release notes for information about changes in Web Agents. component: web-agents version: 2023.11 page_id: web-agents:upgrade:major-upgrade canonical_url: https://docs.pingidentity.com/web-agents/2026/upgrade/major-upgrade.html llms_txt: https://docs.pingidentity.com/web-agents/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md superseded_by: https://docs.pingidentity.com/web-agents/2026/upgrade/major-upgrade.html section_ids: perform_a_major_upgrade: Perform a major upgrade roll_back_from_a_major_upgrade: Roll back from a major upgrade --- # Major upgrade ## Perform a major upgrade 1. Read the [release notes](https://docs.pingidentity.com/web-agents/release-notes/preface.html) for information about changes in Web Agents. 2. Download the agent binaries from the [Ping Identity Download Center](https://backstage.pingidentity.com/downloads). 3. Plan for server downtime. Plan to route client applications to another server until the process is complete and you have validated the result. Make sure the owners of client application are aware of the change, and let them know what to expect. 4. Back up the directories for the agent installation and web server configuration and store them in version control so that you can roll back if something goes wrong: * In [local configuration mode](../user-guide/glossary.html#def-local-configuration-mode): ``` $ cp -r /path/to/web_agents/apache24_agent /path/to/backup $ cp -r /path/to/apache/httpd/conf /path/to/backup ``` * In [centralized configuration mode](../user-guide/glossary.html#def-central-configuration-mode), back up as described in AM's [Maintenance guide](https://docs.pingidentity.com/pingam/7.4/maintenance/backup-restore.html). 5. Redirect client traffic away from the protected website. 6. Stop the web server where the agent is installed. 7. Remove the old Web Agents, as described in [Remove Web Agents](../installation-guide/uninstallation.html). 8. Delete the following shared memory files: * `/dev/shm/am_cache_0` * `/dev/shm/am_log_data_0` Depending on your configuration, the files can be named differently. 9. Install the new agent. In [local configuration mode](../user-guide/glossary.html#def-local-configuration-mode), provide the `agent.conf` file. For more information, refer to [Local configuration (`agent.conf`)](../user-guide/about.html#agentconf). 10. Review the agent configuration: * In [local configuration mode](../user-guide/glossary.html#def-local-configuration-mode), use the backed-up copy of `agent.conf` file for guidance, the agent's [release notes](https://docs.pingidentity.com/web-agents/release-notes/preface.html), and AM's [release notes](https://docs.pingidentity.com/pingam/release-notes/preface.html) to check for changes. Update the file manually to include properties for your environment. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | To prevent errors, make sure the `agent.conf` file contains all required properties. For a list of required properties, refer to [Configuration location](../user-guide/about.html#configuration-location). | * In [centralized configuration mode](../user-guide/glossary.html#def-central-configuration-mode), review the agent's [release notes](https://docs.pingidentity.com/web-agents/release-notes/preface.html) and AM's [release notes](https://docs.pingidentity.com/pingam/release-notes/preface.html) to check for changes. If necessary, change the agent configuration using the AM admin UI. 11. (If you provided the `agent.conf` file to the installer **and** you are upgrading from an agent version earlier than 4.1.0 hotfix 23) Re-encrypt the password specified in the [Agent Profile Password](../properties-reference/com.sun.identity.agents.config.password.html): 1. Obtain the encryption key from the bootstrap property [Agent Profile Password Encryption Key](../properties-reference/com.sun.identity.agents.config.key.html) in the new `agent.conf` file. 2. (Unix only) Store the agent profile password in a file; for example, `newpassword.file`. 3. Encrypt the agent profile password with the encryption key by running the [agentadmin command](../installation-guide/agentadmin.html) with the `--p` option. * Unix * Windows ``` $ ./agentadmin --p "YWM…​Nw=" "cat newpassword.file" Encrypted password value: 07b…​dO4= ``` ``` $ agentadmin.exe --p "YWM…​5Nw=" "newpassword" Encrypted password value: 07b…​dO4= ``` 4. Set the encrypted password as the value of the [Agent Profile Password](../properties-reference/com.sun.identity.agents.config.password.html) property in the new `agent.conf` file. 12. (NGINX Plus and Unix Apache agents only) Configure shared runtime resources and shared memory. For more information, refer to [Configure shared runtime resources and memory](../installation-guide/post-installation.html#configuring-shared-memory). 13. Ensure the communication between AM and the web agent is secured with the appropriate keys. For more information, refer to [Configuring AM to sign authentication information](../installation-guide/pre-installation.html#configuring-agent-communication). 14. Start the web server where the agent is installed. 15. Validate that the agent is performing as expected in the following ways: * Check in `/path/to/web_agents/agent_type/log/system_n.log` that the new version of the agent is running. * Go to a protected page on the website and confirm whether you can access it according to your configuration. * Check logs files for errors. | | | | - | ---------------------------------------------------------------------------------------------------------------------------- | | | To troubleshoot your environment, run the [agentadmin command](../installation-guide/agentadmin.html) with the `--V` option. | 16. Allow client traffic to flow to the protected website. ## Roll back from a major upgrade | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Before you roll back to an earlier version of Web Agents, consider whether any change to the configuration during or since upgrade could be incompatible with the earlier version. | To roll back from a major upgrade, run through the procedure in [Major upgrade](#major-upgrade), but use the backed up directories for the agent installation and web server configuration.