Web Agents 2024.9

Upgrade

Product names changed when ForgeRock became part of Ping Identity. Learn more about the name changes from New names for ForgeRock products.

Web Agent supports the following types of upgrade:

  • Drop-in software update:

    Usually, an update from a version of Web Agent to a newer minor version, as defined in Ping Identity Product Support Lifecycle Policy | PingGateway and Agents. For example, update from 2024.6 to 2024.9 can be a drop-in software update.

    Drop-in software updates can introduce additional functionality and fix bugs or security issues. Consider the following restrictions for drop-in software updates:

    • Don’t require any update to the configuration

    • Can’t cause feature regression

    • Can change default or previously configured behavior only for bug fixes and security issues

    • Can deprecate but not remove existing functionality

  • Major upgrade:

    Usually, an upgrade from a version of Web Agent to a newer major version, as defined in Ping Identity Product Support Lifecycle Policy | PingGateway and Agents. For example, upgrade from 2023.3 to 2024.3 is a major upgrade.

    Major upgrades can introduce additional functionality and fix bugs or security issues. Major upgrades do not have the restrictions of drop-in software update. Consider the following features of major upgrades:

    • Can require code or configuration changes

    • Can cause feature regression

    • Can change default or previously configured behavior

    • Can deprecate and remove existing functionality

This guide describes how to upgrade a single Web Agent instance. To upgrade sites with multiple Web Agent instances, one by one, stop, upgrade, and then restart each server individually, leaving the service running during the upgrade.

For information about upgrade between supported versions of Web Agent, refer to Ping Identity Product Support Lifecycle Policy | PingGateway and Agents.

Example installation for this guide

Unless otherwise stated, the examples in this guide assume the following installation:

  • Web Agent installed on https://agent.example.com:443.

  • AM installed on https://am.example.com:8443/am.

  • Work in the top-level realm /.

If you use a different configuration, substitute in the procedures accordingly.

Drop-in software update

Perform a drop-in software update

  1. Read the release notes for information about changes in Web Agent.

  2. Download the agent binaries from the BackStage download site.

  3. Redirect client traffic away from the protected website.

  4. Stop the web server where the agent is installed.

  5. Replace the following executable files in the current installation with the corresponding files in the downloaded binaries, and make sure that they have the same permissions as the original files:

    • Apache Web Agent:

      • web_agents/apache24_agent/lib/mod_openam.so

      • web_agents/apache24_agent/bin/agentadmin

    • IIS Web Agent:

      • web_agents/iis_agent/lib/mod_iis_openam_64.dll

      • web_agents/iis_agent/lib/mod_iis_openam_64.pdb

      • web_agents/iis_agent/lib/mod_iis_openam_32.dll

      • web_agents/iis_agent/lib/mod_iis_openam_32.pdb

      • web_agents/iis_agent/bin/agentadmin.exe

      • web_agents/iis_agent/bin/agentadmin.pdb

    • ISAPI Web Agent:

      • web_agents/iis_agent/lib/mod_isapi_openam_64.dll

      • web_agents/iis_agent/lib/mod_isapi_openam_64.pdb

      • web_agents/iis_agent/lib/mod_isapi_openam_32.dll

      • web_agents/iis_agent/lib/mod_isapi_openam_32.pdb

      • web_agents/iis_agent/bin/agentadmin.exe

      • web_agents/iis_agent/bin/agentadmin.pdb

    • NGINX Plus Web Agent:

      • web_agents/nginxversion-number_agent/lib/openam_ngx_auth_module.so

      • web_agents/nginxversion-number_agent/bin/agentadmin

        Use the module in the directory for your NGINX version. The following example is for NGINX Plus 29: web_agents/nginx29_agent/lib/openam_ngx_auth_module.so

  6. Start the web server where the agent is installed.

  7. 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 with the --V option.

  8. Allow client traffic to flow to the protected website.

Roll back from a drop-in software update

Before you roll back to an earlier version of Web Agent, consider whether any change to the configuration during or since upgrade could be incompatible with the earlier version.

To roll back from a drop-in software update, run through the procedure in Drop-in software update, but replace the executables with the earlier files, or with those from an earlier version of the agent.

Major upgrade

Perform a major upgrade

  1. Read the release notes for information about changes in Web Agent.

  2. Download the agent binaries from the BackStage download site.

  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:

  5. Redirect client traffic away from the protected website.

  6. Stop the web server where the agent is installed.

  7. Remove the old Web Agent, as described in Remove Web Agent.

  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. If the HTTP proxy or certificate requires credentials, set installation environment variables for one or both of the following properties:

    Learn more from AM_SSL_PASSWORD and AM_PROXY_PASSWORD in Installation environment variables.

  10. Install the new agent.

    In local configuration mode, provide the agent.conf file.

    The installer generates the following files:

  11. Review the agent configuration:

  12. In the new agent-password.conf file, set the value of Agent Profile Password to the value of the encrypted password.

  13. (NGINX Plus and Unix Apache agents only) Configure shared runtime resources and shared memory. Learn more from Configure shared runtime resources and memory.

  14. Ensure the communication between AM and the web agent is secured with the appropriate keys. Learn more from Configuring AM to sign authentication information.

  15. Start the web server where the agent is installed.

    Web Agent 5 changed the default size of the agent session and policy cache from 1 GB to 16 MB. In the unlikely case that an old Apache agent could not release the shared memory, the new Apache agent may not start. For more information, refer to Troubleshoot.

  16. Allow client traffic to flow to the protected website.

  17. 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 with the --V option.

Roll back from a major upgrade

Before you roll back to an earlier version of Web Agent, 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, but use the backed up directories for the agent installation and web server configuration.

Post update and upgrade tasks

After upgrade, review the what’s new section in the release notes and consider activating new features and functionality.

For information about other post-installation options, refer to Post-installation.