Upgrade
For information about upgrade between supported versions of Java Agent, refer to ForgeRock Product Support Lifecycle Policy | IG and Agents.
This section describes how to upgrade a single Java Agent instance. To upgrade sites with multiple Java Agent instances, one by one, stop, upgrade, and then restart each server individually, leaving the service running during the upgrade.
Java Agent supports the following types of upgrade:
-
Drop-in software update:
Usually, an update from a version of Java Agent to a newer minor version, as defined in Release naming. For example, update from 2023.3 to 2023.6 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:
-
Do not require any update to the configuration
-
Cannot 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 Java Agent to a newer major version, as defined in Release naming. For example, upgrade from 5.10 to 2023.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
-
Drop-in software update
The examples in this section assume that the agent is installed in
/path/to/java_agents/agent_type
, and the update is from
the minor version 2023.3 to the minor version 2023.6.
Tomcat Java Agent software update
-
Read the release notes for information about changes in Java Agent.
-
Download the agent binaries from the ForgeRock BackStage download site and extract them to a temporary directory.
The example in this section is extracted to
/tmp
, and the .jar files are in/tmp/tomcat_agent/lib
. -
Back up the directories for the agent installation and the web application container configuration:
-
$ cp -r /path/to/java_agents/tomcat_agent /path/to/backup $ cp -r /path/to/tomcat/webapps/agentapp /path/to/backup
-
In remote configuration mode, back up as described in AM’s Maintenance guide.
-
-
Redirect client traffic away from protected web applications.
-
Stop the web applications where the agent is installed.
-
Locate the following files in the container:
-
agent.jar
-
jee-agents-sdk-version.jar
The following example finds
./lib/jee-agents-sdk-2023.3.jar
: -
-
Replace the following files with the newer downloaded version.
-
agent.jar
-
jee-agents-sdk-version.jar
The following example replaces
./lib/jee-agents-sdk-2023.3.jar
: -
-
(Optional) Update the .jar files outside the container.
-
Using the
.amAgentLocator
file, find the directory in which the agent was originally installed: -
View the content of the
lib
subdirectory:$ cd /path/to/java_agents/tomcat_agent/lib $ ls -F agent.jar jee-agents-installtools-2023.3.jar jee-agents-sdk-2023.3.jar
C:\opt\container> cd C:\opt\installed_agents\java_agents\tomcat_agent\lib C:\opt\installed_agents\java_agents\tomcat_agent\lib> dir Directory of C:\opt\installed_agents\java_agents\tomcat_agent\lib ... agent.jar ... jee-agents-installtools-2023.3.jar ... jee-agents-sdk-2023.3.jar
-
Replace the files with the newer downloaded version:
$ rm -f * $ cp /tmp/java_agents/tomcat_agent/lib/*.jar . $ ls -F agent.jar jee-agents-installtools-2023.6.jar jee-agents-sdk-2023.6.jar
C:\opt\installed_agents\java_agents\tomcat_agent\lib> del *.jar C:\opt\installed_agents\java_agents\tomcat_agent\lib> copy C:\temp\java_agents\tomcat_agent\lib\*.jar . C:\tmp\tomcat_agent\lib\agent.jar C:\tmp\tomcat_agent\lib\jee-agents-installtools-2023.6.jar C:\tmp\tomcat_agent\lib\jee-agents-sdk-2023.6.jar
-
-
Replace the current
agentadmin
file with the newer downloaded version:$ cd /path/to/java_agents/tomcat_agent/bin $ rm agentadmin $ cp /tmp/tomcat_agent/bin/agentadmin .
C:\> cd C:\path\to\java_agents\tomcat_agent\bin C:\path\to\java_agents\tomcat_agent\bin> del agentadmin agentadmin.bat C:\path\to\java_agents\tomcat_agent\bin> copy C:\tmp\tomcat_agent\bin\agentadmin . C:\path\to\java_agents\tomcat_agent\bin> copy C:\tmp\tomcat_agent\bin\agentadmin.bat .
-
Start the web applications where the agent is installed.
-
Check that the agent is performing as expected:
-
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 stringX-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 2023.6
.
-
-
Navigate to a protected page on the website and confirm whether you can access it according to your configuration.
-
Check logs files for warnings and errors.
-
-
Allow client traffic to flow to the protected web applications.
JBoss and WildFly Java Agent software update
-
Read the release notes for information about changes in Java Agent.
-
Download the agent binaries from the ForgeRock BackStage download site and extract them to a temporary directory.
The example in this section is extracted to
/tmp
, and the .jar files are in/tmp/jboss_agent/lib
. -
Back up the directories for the agent installation and the web application container configuration:
-
$ cp -r /path/to/java_agents/jboss_agent /path/to/backup $ cp -r /path/to/jboss/webapps/agentapp /path/to/backup
-
In remote configuration mode, back up as described in AM’s Maintenance guide.
-
-
Redirect client traffic away from protected web applications.
-
Stop the web applications where the agent is installed.
-
Locate the following files in the container:
-
agent.jar
-
jee-agents-jboss-common-version.jar
-
jee-agents-sdk-version.jar
-
tyrus-standalone-client-version.jar
The following example finds
./lib/jee-agents-sdk-2023.3.jar
:$ cd /opt/container $ find . -type f -name 'jee-agents-*.jar' -print ./lib/jee-agents-sdk-2023.3.jar
-
-
Replace the following files with the newer downloaded version.
-
agent.jar
-
jee-agents-jboss-common-version.jar
-
jee-agents-sdk-version.jar
-
tyrus-standalone-client-version.jar
The following example replaces
./lib/jee-agents-sdk-2023.3.jar
:$ cd /opt/container $ rm -f lib/jee-agents-sdk-2023.3.jar $ cp /tmp/jboss_agent/lib/jee-agents-sdk-2023.6.jar lib
-
-
In the JBoss
module.xml
file, change the agent version number from the old value to the new value. For example, change2023.3
to2023.6
.The
module.xml
file is in the path to your JBoss installation, for example, at/opt/jboss/jboss/modules/org/forgerock/openam/agent/main/modules/org/forgerock/openam/agent/main
. -
(Optional) Update the .jar files outside the container.
-
Using the
.amAgentLocator
file, find the directory in which the agent was originally installed:$ cd /opt/container $ cat .amAgentLocator; echo /path/to/java_agents/jboss_agent
-
View the content of the
lib
subdirectory:$ cd /path/to/java_agents/jboss_agent/lib $ ls -F agent.jar jee-agents-jboss-common-version.jar jee-agents-sdk-version.jar tyrus-standalone-client-version.jar
-
Replace the files with the newer downloaded version:
$ rm -f * $ cp /tmp/java_agents/jboss_agent/lib/*.jar . $ ls -F agent.jar jee-agents-jboss-common-version.jar jee-agents-sdk-version.jar tyrus-standalone-client-version.jar
-
-
Replace the current
agentadmin
file with the newer downloaded version:$ cd /path/to/java_agents/jboss_agent/bin $ rm agentadmin $ cp /tmp/jboss_agent/bin/agentadmin .
-
Start the web applications where the agent is installed.
-
Check that the agent is performing as expected:
-
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 stringX-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 2023.6
.
-
-
Navigate to a protected page on the website and confirm whether you can access it according to your configuration.
-
Check logs files for warnings and errors.
-
-
Allow client traffic to flow to the protected web applications.
Jetty Java Agent software update
-
Read the release notes for information about changes in Java Agent.
-
Download the agent binaries from the ForgeRock BackStage download site and extract them to a temporary directory.
The example in this section is extracted to
/tmp
, and the .jar files are in/tmp/jetty_agent/lib
. -
Back up the directories for the agent installation and the web application container configuration:
-
$ cp -r /path/to/java_agents/jetty_agent /path/to/backup $ cp -r /path/to/jetty/webapps/agentapp /path/to/backup
-
In remote configuration mode, back up as described in AM’s Maintenance guide.
-
-
Redirect client traffic away from protected web applications.
-
Stop the web applications where the agent is installed.
-
Replace the following files with the newer downloaded versions.
-
agent.jar
-
jee-agents-installtools-version.jar
-
jee-agents-sdk-version.jar
The following example replaces
jee-agents-sdk-2023.3.jar
:$ cd /path/to/java_agents/jetty_agent/lib $ rm -f jee-agents-sdk-2023.3.jar $ cp /tmp/jetty_agent/lib/jee-agents-sdk-2023.6.jar .
-
-
Update the Jetty configuration:
-
Go to the Jetty base directory.
$ cd /path/to/jetty-base/modules
-
In
amlogin.mod
, update the version number forjee-agents-sdk-version.jar
. The following example includesjee-agents-sdk-2023.3.jar
:# Jetty AM module # [depend] server security jndi webapp plus [xml] etc/amlogin.xml [lib] /opt/java_agents/jetty_agent/Agent_001/config /opt/java_agents/jetty_agent/locale /opt/java_agents/jetty_agent/lib/agent.jar /opt/java_agents/jetty_agent/lib/jee-agents-sdk-2023.3.jar
-
-
Replace the current
agentadmin
file with the newer downloaded version:$ cd /path/to/java_agents/jetty_agent/bin $ rm agentadmin $ cp /tmp/jetty_agent/bin/agentadmin .
-
Start the web applications where the agent is installed.
-
Check that the agent is performing as expected:
-
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 stringX-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 2023.6
.
-
-
Navigate to a protected page on the website and confirm whether you can access it according to your configuration.
-
Check logs files for warnings and errors.
-
-
Allow client traffic to flow to the protected web applications.
WebLogic Java Agent software update
-
Read the release notes for information about changes in Java Agent.
-
Download the agent binaries from the ForgeRock BackStage download site and extract them to a temporary directory.
The example in this section is extracted to
/tmp
, and the .jar files are in/tmp/weblogic_agent/lib
. -
Back up the directories for the agent installation and the web application container configuration:
-
$ cp -r /path/to/java_agents/weblogic_agent /path/to/backup
-
In remote configuration mode, back up as described in AM’s Maintenance guide.
-
-
Add the following file to the backup:
-
/Oracle/Middleware/Oracle_Home/user_projects/domains/base_domain/setAgentEnv_AdminServer.sh
-
-
Redirect client traffic away from protected web applications.
-
Stop the web applications where the agent is installed.
-
Update the .jar files outside the container.
-
Using the
.amAgentLocator
file, find the directory in which the agent was originally installed:$ cd /opt/container $ cat .amAgentLocator; echo /path/to/java_agents/weblogic_agent
-
View the content of the
lib
subdirectory:$ cd /path/to/java_agents/weblogic_agent/lib $ ls -F agent.jar jee-agents-installtools-2023.3.jar jee-agents-sdk-2023.3.jar
-
Replace the files with the newer downloaded version:
$ rm -f * $ cp /tmp/java_agents/weblogic_agent/lib/*.jar . $ ls -F agent.jar jee-agents-installtools-2023.6.jar jee-agents-sdk-2023.6.jar
-
-
Update the environment settings:
-
Locate the
setAgentEnv_AdminServer.sh
file. The file can be in a directory such as/Oracle/Middleware/Oracle_Home/user_projects/domains/base_domain/
. -
Change the version number for the agent files to the new version. The following example is for Java Agent 2023.3:
... # Append AGENT_CLASSPATH to the WebLogic server classpath AGENT_CLASSPATH="/path/to/java_agents/weblogic_agent/lib/agent .jar:/path/to/java_agents/weblogic_agent/lib/jee-agents-installtools-launcher-2023.3 .jar:/path/to/java_agents/weblogic_agent/lib/jee-agents-sdk-2023.3 .jar:/path/to/java_agents/weblogic_agent/lib/jee-agents-installtools-2023.3 .jar:/path/to/java_agents/weblogic_agent/locale:/path/to/java_agents/weblogic_agent/Agent_001/config" CLASSPATH="${CLASSPATH}${CLASSPATHSEP}${AGENT_CLASSPATH}" export CLASSPATH ...
-
Remove the following line for the installation launcher:
.jar:/path/to/java_agents/weblogic_agent/lib/jee-agents-installtools-launcher-version
.The installation launcher was removed in Java Agent 2023.6.
-
Save the file.
-
-
Replace the current
agentadmin
file with the newer downloaded version:$ cd /path/to/java_agents/weblogic_agent/bin $ rm agentadmin $ cp /tmp/weblogic_agent/bin/agentadmin .
-
Start the web applications where the agent is installed.
-
Check that the agent is performing as expected:
-
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 stringX-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 2023.6
.
-
-
Navigate to a protected page on the website and confirm whether you can access it according to your configuration.
-
Check logs files for warnings and errors.
-
-
Allow client traffic to flow to the protected web applications.
Major upgrade
Perform a major upgrade
-
Read the release notes for information about changes in Java Agent.
-
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.
-
Download the agent binaries from the ForgeRock BackStage download site.
-
Back up the directories for the agent installation and the web application container configuration:
-
$ cp -r /path/to/java_agents/agent_type /path/to/backup $ cp -r /path/to/agent_type/webapps/agentapp /path/to/backup
-
In remote configuration mode, back up as described in AM’s Maintenance guide.
-
-
Redirect client traffic away from protected web applications.
-
Stop the web applications where the agent is installed.
-
Remove the old Java Agent, as described in Remove Java Agent.
-
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:
-
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.
-
-
Secure communication between AM and the agent with appropriate keys. For information, see Configure AM servers to communicate with Java Agents.
-
Start the web applications where the agent is installed.
-
Check that the agent is performing as expected:
-
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 stringX-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 2023.6
.
-
-
Navigate to a protected page on the website and confirm whether you can access it according to your configuration.
-
Check logs files for warnings and errors.
-
-
Allow client traffic to flow to the protected web applications.
Post update and upgrade tasks
After upgrade or update, 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 tasks.