Java Agents 2023.11.2

Major upgrade

Perform a major upgrade

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

  2. 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 applications are aware of the change, and let them know what to expect.

  3. Download the agent binaries from the ForgeRock BackStage download site.

  4. Back up the directories for the agent installation and the web application container configuration:

  5. Redirect client traffic away from protected web applications.

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

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

  8. Install the new agent.

    The installer creates new versions of the following files, with configuration that is relevant to the new version of the agent:

  9. Using the agent’s release notes and AM’s release notes, check for changes and update the configuration.

    To prevent errors, do not copy configuration files from the previous installation to the new installation. Use the new version of the files and update then as necessary.

    • In local configuration mode, update AgentConfiguration.properties manually to include properties for your environment, using backed-up files for guidance.

      The AgentBootstrap.properties file created by the installer contains bootstrap properties relevant to the new version of the agent.

    • In remote configuration mode, change the agent configuration using the AM admin UI.

  10. Secure communication between AM and the agent with appropriate keys. For information, refer to Configure AM servers to communicate with Java Agents.

  11. Start the web applications where the agent is installed.

  12. Check that the agent is performing as expected:

    1. Check the correct version of the agent is running:

      • Set the log level to trace, as described in Logging.

      • In /path/to/java_agents/agent_type/Agent_n/logs/debug, search for lines containing the string X-ForgeRock-Edge-Metadata. The version number is given in the header.

        For example, the log file can contain the following header: --header "X-ForgeRock-Edge-Metadata: JPA ${current.minor.version}.

    2. Navigate to a protected page on the website and confirm whether you can access it according to your configuration.

    3. Check logs files for warnings and errors.

  13. Allow client traffic to flow to the protected web applications.

Roll back from a major upgrade

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