This section describes Web Agent properties that are configured by environment variables. After setting an environment variable, restart the container where Web Agent is running.
Configure environment variables to affect the user that is running the web server, virtual host, or location that the agent protects.
|For information about allowing environment variables to be used in NGINX, see the env directive in the NGINX Core functionality documentation.|
(Unix only) The base number for IPC identifiers used by the agent. The shared memory semaphore ID range used by the agent starts at the specified value. Set this variable only if you detect that the agent semaphores are clashing with those of other processes in your environment.
The default is an arbitrary value.
The maximum number of agent instances in the installation. The higher the number, the more shared memory the agent reserves. The default value is
Once the number is met, any additional agent instances that start will log an error, and will not protect resources.
The maximum size of the shared memory for the session and policy cache, in bytes:
Not set, or set to
For multiple concurrent sessions, consider using a higher value.
The number of seconds for which the agent installer can contact AM during agent configuration validation.
If the installer takes longer than this value to contact AM and validate the configuration, installation fails.
Default: 4 seconds
onto enable the policy cache.
You must also specify a directory in which to store the policies in the
The directory in which to store the policy cache. The agent must be able to write to this directory. For example,
(Unix only) The permissions that the agent sets for its runtime resources. Possible values are:
AM_RESOURCE_PERMISSIONSenvironment variable requires the
umaskvalue to allow these permissions for the files.
Consider an example where the Apache agent is running with the
umaskvalue is set to
AM_RESOURCE_PERMISSIONSenvironment variable is set to
0666. The agent runtime resources will have the following permissions:
Resource Permissions Example in Linux Resource Permission Owner
Any semaphores owned by the
644permissions as well.
Consider another example where
umaskis set to
0002and the ` AM_RESOURCE_PERMISSIONS` environment variable is set to
0666. The files would be created with
664permissions, which would allow the files to be read and written by the members of the group, as well.
Overrides the default SSL/TLS protocols for the agent, set in the Security Protocol List bootstrap property.
Specifies a space-separated list of security protocols preceded by a dash (
-) that will not be used when connecting to AM.
The following protocols are supported:
For example, to configure
TLSv1.1, set the environment variable to
AM_SSL_OPTIONS = -SSLv3 -TLSv1 -TLSv1.2.
The log level of garbage collector statistics for all Web Agent instances in the container. The logs are written into the
nindicates the agent group number.
Consider an environment with two Apache server installations:
Apache_1has two agent instances configured,
agent_2, configured to share runtime resources (AmAgentId is set to 0). Both agent instances will write to the
Apache_2has one agent instance configured,
agent_3, with AmAgentId set to 1. The instance will write to the
By default, the
system_n.logfile is stored in the
/path/to/web_agents/agent_type/logdirectory. To modify its path or its size, configure the
system_n.logfile can contain the following information:
Agent version information, written when the agent instance starts up.
Logs for the agent background processes.
WebSocket connection errors.
Cache stats and removal of old POST data preservation files.
The default value of the
Error. Increase it to
Allfor fine-grained detail.
Valid values for the variable are:
The directory where the
system_n.logfile is stored.
By default, this environment variable is configured to
Thesize, in bytes, of the
The default is
0, which specifies that the log file size is unlimited. Valid ranges for this variable go from 0 to 4294967295 bytes (4GB).
(Unix only) Thedirectory where the agent instances will store their temporary pipe files.
The default is
Use the following properties during agent installation.
For example, use the
AM_SSL_* environment properties to install agents when
SSL is already configured in AM or in the agent container.
The install process will set the values in the environment variables as part of
the agent configuration if the process is successful.
You may also use these settings with the
agentadmin -V[i] command if
you want to test values different from those already configured for the agent
When AM and the agent communicate through a proxy configured in forward proxy mode, this environment variable specifies the proxy FQDN.
When AM and the agent communicate through a proxy configured in forward proxy mode, and the proxy requires that the agent authenticates using Basic Authentication, this environment variable specifies the password of the agent.
When AM and the agent communicate through a proxy configured in forward proxy mode, and the proxy requires the agent authenticates using Basic Authentication, this environment variable specifies the user name of the agent.
When AM and the agent communicate through a proxy configured in forward proxy mode, this variable specifies the proxy port number.
The user running the Apache HTTP or IBM HTTP Server.
Use this variable if there is no Apache user defined in the
The group to which the user running the Apache HTTP or IBM HTTP Server belongs.
Use this variable if there is no Apache group defined in the
(Windows only) Specifies whether the agent installation process should use the Windows Secure Channel API. Possible values are:
0. Disable Windows Secure Channel API support. The agent will use OpenSSL libraries instead.
Ensure that the OpenSSL libraries are in the appropriate place, as specified in the OpenSSL Library Location by Operating System table.
1. Enable Windows Secure Channel API support.
(OpenSSL only) When AM is configured to perform client authentication, this environment variable specifies a PEM file that contains the private key corresponding to the certificate specified in the
AM_SSL_CERTenvironment variable. For example,
(OpenSSL only) When AM is configured to perform client authentication, this environment variable specifies the obfuscated password of the private key configured in the
AM_SSL_KEYvariable. Configure this variable only if the private key is password-protected.
To obfuscate the password, use the
agentadmin --pcommand. For example:
$ /path/to/web_agents/agent_type/bin/> agentadmin --p "Encryption Key" “cat certificate_password.file” Encrypted password value: zck+6RKqjtc=com.forgerock.agents.config.cert.key.password = zck+6RKqjtc=
C:\path\to\web_agents\agent_type\bin> agentadmin.exe --p "Encryption_Key" "Certificate_File_Password" Encrypted password value: zck+6RKqjtc=
(OpenSSL only) The list of ciphers to support. The list consists of one or more cipher strings separated by colons, as defined in the man page for ciphers available at http://www.openssl.org/docs/apps/ciphers.htm.
When AM is configured to perform client authentication, this environment variable specifies a PEM file that contains the certificate chain for the agent.
C:\Certificates\client-cert.pem(Windows with OpenSSL), or
Cert:\LocalMachine\My location(Windows with the Windows Secure Channel API).
When configuring the agent to validate AM’s certificate, this environment variable specifies a PEM file that contains the certificates required to validate AM’s server certificate. For example,
C:\Certificates\ca.pem(Windows with OpenSSL), or
Cert:\LocalMachine\Ca(Windows with the Windows Secure Channel API).
agentadmin command manages Web Agent installation. It returns
0) when it completes successfully, and
(or a code greater than zero) when it fails.
The following options are supported:
Install a new agent instance.
Silently, non-interactively, install a new agent instance.
agentadmin --s web-server-config-file openam-url agent-url realm agent-profile-name agent-profile-password [--changeOwner] [--acceptLicense] [--forceInstall]
(Apache HTTP Server) The full path to the Apache HTTP server configuration file. The installer modifies this file to include the agent configuration and module.
(Microsoft IIS) The ID number of the IIS site in which to install the web agent. To list the available sites in an IIS server and the relevant ID numbers, run
The full URL of the AM instance that the agent will use. Ensure the deployment URI is specified.
If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example,
https://proxy.example.com:443/openam. For information about setting up an environment for reverse proxies, see Configuring Apache HTTP Server as a Reverse Proxy Example.
Enter the full URL of the server on which the agent is running.
Enter the AM realm containing the agent profile.
The name of the agent profile in AM.
The full path to the agent profile password file.
(Apache web agent for Unix only) Use this option to set the ownership of created directories to the user and group as specified in the Apache configuration file.
Note that this option will only change the ownership of the files and directories if you run the
agentadmincommand as the
rootuser or using the
If you cannot run the
rootuser or using the
sudocommand, you must change the ownership manually.
When you run certain commands, you will be prompted to read and accept the software license agreement. You can suppress the license agreement prompt by including the optional
--acceptLicenceparameter. Specifying this options indicates that you have read and accepted the terms stated in the license.
To view the license agreement, open
Add this option to proceed with a silent installation even if it cannot connect to the specified AM server during installation, rather than exiting.
(IIS web agent only) List the sites available in an IIS server.
c:\web_agents\iis_agent\bin> agentadmin.exe --nIIS Server Site configuration: ==================================== id details ==================================== Default Web Site application path:/, pool DefaultAppPool 1.1.1 virtualDirectory path:/, configuration: C:\inetpub\wwwroot\web.config MySite application path:/, pool: MySite 2.1.1 virtualDirectory path:/, configuration C:\inetpub\MySite\web.config application path:/MyApp1, pool: MySite
List existing configured agent instances.
$ ./agentadmin --l OpenAM Web Agent configuration instances: id: agent_1 configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_1 server/site: /etc/httpd/conf/httpd.conf id: agent_2 configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_2 server/site: /etc/httpd/conf/httpd.conf id: agent_3 configuration: /opt/web_agents/apache24_agent/bin/../instances/agent_3 server/site: /etc/httpd/conf/httpd.conf
(IIS web agent only) Remove all web agent instances and libraries from an IIS installation.
For more information, see To Remove Web Agents from IIS.
(IIS web agent only) Enable an existing agent instance.
agentadmin.exe --e agent-instance
For more information, see To Disable and Enable Web Agents.
(IIS web agent only) Disable an existing agent instance.
agentadmin.exe --d agent-instance
For more information, see To Disable and Enable Web Agents.
(IIS web agent only) Modify Access Control Lists (ACLs) for files and folders related to a web agent instance.
agentadmin.exe --o "identity_or_siteID" "directory" [--siteId]
agentadmin.exe --o "directory" --addAll --removeAll
Specifies the identity to be added to the directory’s ACLs. When used with the
--siteIdoption, it specifies an IIS site ID.
Specifies the directory that would be modified.
Specifies that the
identity_or_siteIDas an IIS site ID.
Add all IIS application pool identities to the directory’s ACLs. This option is not compatible with the
Remove all IIS application pool identities from the directory’s ACLs. This option is not compatible with the
C:\web_agents\iis_agent\bin> agentadmin.exe --o "IIS_user1" "C:\web_agents\iis_agent\lib"
C:\web_agents\iis_agent\bin> agentadmin.exe --o "2" "C:\web_agents\iis_agent\lib" --siteId
C:\web_agents\iis_agent\bin> agentadmin.exe --o "C:\web_agents\iis_agent\lib" --addAll
Remove an existing agent instance.
agentadmin --r agent-instance
The ID of the web agent configuration instance to remove.
yeswhen prompted to confirm removal.
On IIS web agents, the
--roption does not remove the web agent libraries since they can be in use by other web agent instances configured on the same site. To remove all web agent instances and libraries, use the
Generate a new signing key.
Use a generated encryption key to encrypt a new password.
agentadmin --p encryption-key password
An encryption key, generated by the
The password to encrypt.
Validate an agent instance.
agentadmin --V[i] agent_instance [user name] [password file] [realm]
(Optional) Ensures that the core init and shutdown agent sequences are working as expected.
Do not use this option while the agent is actively protecting a website. Doing so may make the agent instance unresponsive, causing unexpected service outages.
(Required) The agent instance where to run the validation tests. For example,
- user name
(Optional) A user ID that exists in the AM server. Required only for the
validate_session_profiletest. For example,
- password file
(Optional) A file containing the password of the user ID used for the
validate_session_profiletest. For example,
(Optional) The realm of the user ID used for the
validate_session_profiletest. For example,
Validation mode performs tests to ensure the following points:
The agent can reach the AM server(s) configured in AM Connection URL.
Critical bootstrap properties are set. For more information, see Configuration Location.
SSL libraries are available and that SSL configuration properties are set, if the agent is configured for SSL communication.
The agent can log in to AM to fetch the agent profile.
The system has enough RAM and shared memory.
The agent can log in to AM with the provided user and password credentials.
WebSocket connections are available between the agent and AM.
The core init and shutdown agent sequences are working as expected.
This validation requires the
--Viflag. Do not use this option while the agent instance is actively protecting a website. Doing so may make the agent instance unresponsive, causing unexpected service outages.
(IIS agent only) That IIS is configured for running application pools in Integrated mode.
On Unix, you should run the
agentadmin --V[i]validator command as the same user that runs the web server.
For example, to use the Apache HTTP Server
$ sudo -u daemon ./bin/agentadmin --V agent_1
Running the command as a different user may cause the
log/monitor_0.pipefiles to be created with permissions that prevent the agent from writing to them. In this case, you may see an error such as:
2018-09-19 13:54:52 GMT ERROR [0x7f0c9cf05700:22420]: unable to open event channel
If you have run the validator command as any other user, ensure the agent files have the correct permissions. For more information, review the installation instructions for your web agent in Install Web Agent.
$ ./agentadmin --Vi agent_1 demo passwd.txt / Saving output to /web_agents/apache24_agent/bin//../log/validate_20180831121402.log Running configuration validation for agent_1: Agent instance is configured with 1 naming.url value(s): 1. https://openam.example.com:8443/openam is valid selected https://openam.example.com:8443/openam as naming.url value validate_bootstrap_configuration: ok validate_ssl_libraries: ok validate_agent_login: ok get_allocator_blockspace_sz(): trying for configured cache size 16777216 bytes validate_system_resources: ok validate_session_profile: ok validate_websocket_connection: ok validate_worker_init_shutdown: ok Result: 7 out of 7 tests passed, 0 skipped.
Display information about
agentadminbuild and version numbers, and available system resources.
AM Web Agent for IIS Server 7.5, 8.x Version: 5.9 Revision: ab12cde Build machine: WIN-6R2CH15R77 Build date: Nov 8 2016 11:30:18 System Resources: total memory size: 7.7GB pre-allocated session/policy cache size: 1.0GB log buffer size: 128.5MB min audit log buffer size: 2MB, max 2.0GB total disk size: 162.4GB free disk space size: 89.6GB System contains sufficient resources (with remote audit log feature enabled).
This section contains an example configuration of Apache as a reverse proxy between AM and Web Agent. You can use any reverse proxy that supports the WebSocket protocol.
For information about how to configure Apache for load balancing, and other requirements for your environment, see the Apache documentation.
httpd.conffile in your deployed reverse proxy instance.
Add the modules required for a proxy configuration, as follows:
# Modules required for proxy LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_http_module modules/mod_proxy_http.so LoadModule proxy_wstunnel_module modules/mod_proxy_wstunnel.so
mod_proxy_wstunnel.somodule is required to support the WebSocket protocol used for communication between AM and the agents.
Add the proxy configuration inside the
VirtualHostcontext. Consider the following directives:
<VirtualHost 192.168.1.1> ... # Proxy Config RequestHeader set X-Forwarded-Proto "https" (1) ProxyPass "/openam/notifications" "ws://openam.example.com:8080/openam/notifications" Upgrade=websocket (2) ProxyPass "/openam" "http://openam.example.com:8080/openam" (3) ProxyPassReverseCookieDomain "openam.internal.example.com" "proxy.example.com" (4) ProxyPassReverse "/openam" "http://openam.example.com:8080/openam" (5) ... </VirtualHost>
(1) RequestHeader: Set to
http, depending on the proxy configuration. If the proxy is configured for https, as in the above example, set to
https. Otherwise, set
http. In a later step, you configure AM to recognize the forwarded header and use it in the
gotoparameter for redirecting back to the agent after authentication.
(2) ProxyPass: Set to allow WebSocket traffic between AM and the agent. If HTTPS is configured between the proxy and AM, set to use the
wssprotocol instead of
(3) ProxyPass: Set to allow HTTP traffic between AM and the agent.
(4) ProxyPassReverseCookieDomain: Set to rewrite the domain string in `Set-Cookie`headers in the format internal domain (AM’s domain) public domain (proxy’s domain).
(5) ProxyPassReverse: Set to the same value configured for the
For more information about configuring Apache as a reverse proxy, see the Apache documentation.
Restart the reverse proxy instance.
Configure AM to recover the forwarded header you configured in the reverse proxy. Also, review other configurations that may be required in an environment that uses reverse proxies. For more information, see Regarding Communication Between AM and Agents