How do I upgrade to Web Policy Agent 4.x from a previous version?
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:
- Installing Web Policy Agents 4.2 in Apache HTTP Server
- Installing Web Policy Agents 4.2 in Microsoft IIS
- Installing Web Policy Agents 4.2 in NGINX Plus
- Installing Web Policy Agents 4.1 in Microsoft IIS
- Installing Web Policy Agents 4.1 in Apache HTTP Server
- Installing Apache Web Policy Agents 4.1 into a Virtual Host
- Installing Web Policy Agents 4 in Microsoft IIS
- Installing Web Policy Agents 4 in Apache HTTP Server
- Installing Apache Web Policy Agents 4 into a Virtual Host
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
See Also
Tips and feature insights for Web Policy Agents 4.x
Best practice for installing IIS Web Agents (All versions)
What versions of Agents are compatible with AM?
Web Policy Agent 4.1 Guide › Removing Apache Web Policy Agents
Web Policy Agent 4.1 Guide › Managing IIS Web Policy Agents
OpenAM Web Policy Agent 4 User's Guide › Removing Apache Web Policy Agents
OpenAM Web Policy Agent 4 User's Guide › Removing IIS Web Policy Agents
OpenAM Web Policy Agent 3.x Installation Guide › Remove Apache 2.4 Web Policy Agent Software
OpenAM Web Policy Agent 3.x Installation Guide ›Remove Apache 2.2 Web Policy Agent
OpenAM Web Policy Agent 3.x Installation Guide › Remove IIS 7 Web Policy Agent Software
OpenAM Web Policy Agent 3.x Installation Guide › Remove IIS 6 Web Policy Agent Software
Related Training
N/A
Related Issue Tracker IDs
OPENAM-7452 (WPA4 agent might crash in configuration validation phase (silent install) )