How do I upgrade to Web Policy Agent 4.x from a previous version?

Last updated Jan 5, 2021

The purpose of this article is to provide information on upgrading to Web Policy Agent 4.x from a previous version. This process allows you to use the same agent configuration used previously.

1 reader recommends this article

Archived

This article has been archived and is no longer maintained by ForgeRock.

Prerequisites

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues.

Before upgrading your Web policy agent, you should:

Back up your policy agent configuration as detailed in How do I export configuration details for the Agent (All versions)?
Read the Web Policy Agent 4.2 Release Notes, OpenAM Web Policy Agent 4.1 Release Notes, OpenAM Web Policy Agent 4 Release Notes and Tips and feature insights for Web Policy Agents 4.x so that you are fully aware of all the changes.
Read the Before You Install section in the release notes for the applicable agent and ensure all the prerequisites are met.

Upgrading to Web Policy Agent 4.x

Note

Please note the following:

You should upgrade to Web policy agent 4.2, which includes fixes to a number of known issues; you can download this from BackStage.
As part of the install process, you must uninstall the previous version of the web policy agent; Web policy agent 4 cannot coexist with a previous version.
If you are using a centralized configuration, Web policy agent 4.x will automatically be installed using the same agent configuration used previously.

You can upgrade your Web Policy Agent as follows:

Copy the OpenSSOAgentConfiguration.properties file if you have a local configuration and want to retain your previous configuration.
Uninstall the previous version of the web policy agent; Web policy agent 4 cannot coexist with a previous version. Uninstalling the web policy agent will not affect the policy agent profile in AM/OpenAM. After uninstalling the IIS 7 policy agent, follow the steps below in the Checking IIS Policy Agent is completely uninstalled section to ensure it is completely removed before you install the new policy agent.
Install OpenSSL if the AM/OpenAM server you will be connecting to uses SSL and the operating system does not provide native openssl packages. You can download OpenSSL from: https://www.openssl.org/. If you are using Microsoft® Windows®, you can use the native Schannel for SSL communication as of Web policy agent 4.1; see OpenAM Web Policy Agent Release Notes › What's New in Web Policy Agents 4.1 › New Features in Web Policy Agents 4.1.0 for further information.
Install the web policy agent 4.x using the documented procedure for your specific agent/version:

Silent install

If you are performing a silent, non-interactive installation by running agentadmin --s, you can optionally add the --forceInstall option. This option forces the installer to proceed with the silent installation even if it cannot connect to the specified AM/OpenAM server during installation. If your install fails, you should try performing a silent non-interactive installation with this option added, for example:

Unix® or Linux® system: $ agentadmin --s --forceInstall
Microsoft Windows: C:\> agentadmin.exe --s --forceInstall

See How do I silently remove a Web Agent (All versions)? for information on silently removing agents.

Checking IIS Policy Agent is completely uninstalled

There is a known issue with the uninstaller for IIS 3.x agents where it can fail to completely uninstall the agent. You should follow these steps (using the IIS Manager or command line as preferred) to ensure the agent has been completely uninstalled prior to installing web agent 4.x or later 3.x releases:

Using IIS Manager

Launch the IIS Manager.
Expand the required Server node in the Connections pane, select Sites followed by the Site name.
Click Modules under IIS to display the list of modules for the site.
If the iis7agent module is listed, right-click on it and remove it. If it is not listed, proceed to the next step.
Repeat steps 2 to 4 for each site.
Select the Server name in the Connections pane.
Click Modules under IIS to display the list of modules for the server.
If the iis7agent module is listed, right-click on it and remove it. If it is not listed, proceed to the next step.
Select the Configure Native modules option from the Actions pane whilst the Server > Modules configuration is displayed.
If the iis7agent module is listed, select it and click Remove. If it is not listed, proceed to the next step.
Restart the IIS process or Microsoft Windows by running C:\> iisreset

Using the command line

List the sites and modules using the following commands: C:\> appcmd.exe list sites C:\> appcmd.exe list modules
Run the following command for the first site listed, replacing "Default Web Site/" with the site name: C:\> appcmd.exe list config "Default Web Site/" /section:globalModules
Run the following commands if the iis7agent module is listed: C:\> appcmd.exe delete module /module.name:iis7agent /commit C:\> appcmd.exe uninstall module /module.name:iis7agent /commit
Repeat steps 2 and 3 for all the remaining sites that were listed in step 1.
Restart the IIS process or Microsoft Windows by running C:\>iisreset

Related Training

N/A

Related Issue Tracker IDs

OPENAM-7452 (WPA4 agent might crash in configuration validation phase (silent install) )

OPENAM-8065 (WPA4 agentadmin installer fails in send_session_request when notifications are disabled in OpenAM)

Archived

Prerequisites

Note

Upgrading to Web Policy Agent 4.x

Note

Checking IIS Policy Agent is completely uninstalled

See Also

Related Training

Related Issue Tracker IDs