Major upgrade
Perform a major upgrade
-
Read the release notes for information about changes in Web Agent.
-
Download the agent binaries from the ForgeRock BackStage download site.
-
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.
-
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:
-
$ cp -r /path/to/web_agents/apache24_agent /path/to/backup $ cp -r /path/to/apache/httpd/conf /path/to/backup
-
In centralized configuration mode, back up as described in AM’s Maintenance guide.
-
-
Redirect client traffic away from the protected website.
-
Stop the web server where the agent is installed.
-
Remove the old Web Agent, as described in Remove Web Agent.
-
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.
-
-
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.
-
Install the new agent.
In local configuration mode, provide the agent.conf file.
The installer generates the following files:
-
agent-key.conf containing the Agent Profile Password Encryption Key
-
agent-password.conf containing the Agent Profile Password
When the HTTP proxy or certificate requires credentials,
agent-password.confshould also contain one or both of Private Key Password and Proxy Server Password.
-
-
Review the agent configuration:
-
In local configuration mode, use the backed-up copy of
agent.conffile for guidance, the agent’s release notes, and AM’s Release notes to check for changes. Update the file manually to include properties for your environment.To prevent errors, make sure the agent.conffile contains all required properties. For a list of required properties, refer to Configuration files. -
In centralized configuration mode, review the agent’s release notes and AM’s Release notes to check for changes. If necessary, change the agent configuration using the AM admin UI.
-
-
In the new
agent-password.conffile, set the value of Agent Profile Password to the value of the encrypted password. -
(NGINX Plus and Unix Apache agents only) Configure shared runtime resources and shared memory. Learn more from Configure shared runtime resources and memory.
-
Ensure the communication between AM and the web agent is secured with the appropriate keys. Learn more from Configuring AM to sign authentication information.
-
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 Troubleshooting. -
Allow client traffic to flow to the protected website.
-
Validate that the agent is performing as expected in the following ways:
-
Check in
/path/to/web_agents/agent_type/log/system_n.logthat 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 --Voption. -
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.