Reference

Environment Variables

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.

AM_IPC_BASE

(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.

AM_MAX_AGENTS

The maximum number of agent instances in the installation. The higher the number, the more shared memory the agent reserves. The default value is 32.

Once the number is met, any additional agent instances that start will log an error, and will not protect resources.

AM_MAX_SESSION_CACHE_SIZE

The maximum size of the shared memory for the session and policy cache, in bytes:

Not set, or set to 0: 16777216 (16 MB)
Maximum value: 1073741824 (1 GB)
Minimum value 1024 (1 MB)

For multiple concurrent sessions, consider using a higher value.

AM_NET_TIMEOUT

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

AM_POLICY_CACHE_MODE

Set to on to enable the policy cache.

You must also specify a directory in which to store the policies in the AM_POLICY_CACHE_DIR environment variable.

AM_POLICY_CACHE_DIR

The directory in which to store the policy cache. The agent must be able to write to this directory. For example, /path/to/web_agents/<agent_type>/log.

AM_RESOURCE_PERMISSIONS

(Unix only) The permissions that the agent sets for its runtime resources. Possible values are:

0600
0660
0666

The AM_RESOURCE_PERMISSIONS environment variable requires the umask value to allow these permissions for the files.

Consider an example where the Apache agent is running with the apache user. The umask value is set to 0022 and the AM_RESOURCE_PERMISSIONS environment variable is set to 0666. The agent runtime resources will have the following permissions:

Resource Permissions Example in Linux
Resource	Permission	Owner
`/path/to/web_agents/agent_type/log/system_n.log`	644	`apache`
`/path/to/web_agents/agent_type/log/monitor_n.log`	644	`apache`
`/path/to/web_agents/agent_type/instances/agent_n/conf/agent.conf`	640	`apache`
`/path/to/web_agents/agent_type/instances/agent_n/logs/debug/debug.log`	644	`apache`
`/dev/shm/am_cache_0`	644	`apache`
`/dev/shm/am_log_data_0`	644	`apache`

Any semaphores owned by the apache user have 644 permissions as well.

Consider another example where umask is set to 0002 and the ` AM_RESOURCE_PERMISSIONS` environment variable is set to 0666. The files would be created with 664 permissions, which would allow the files to be read and written by the members of the group, as well.

AM_SSL_OPTIONS

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:

SSLv3
TLSv1
TLSv1.1
TLSv1.2 (Enabled)
TLSv1.3 (Enabled)

For example, to configure TLSv1.1, set the environment variable to AM_SSL_OPTIONS = -SSLv3 -TLSv1 -TLSv1.2.

AM_SYSTEM_LOG_LEVEL

The log level of garbage collector statistics for all Web Agent instances in the container. The logs are written into the system_n.log file, where n indicates the agent group number.

Consider an environment with two Apache server installations:

Apache_1 has two agent instances configured, agent_1 and agent_2, configured to share runtime resources (AmAgentId is set to 0). Both agent instances will write to the system_0.log file.
Apache_2 has one agent instance configured, agent_3, with AmAgentId set to 1. The instance will write to the system_1.log file.

By default, the system_n.log file is stored in the /path/to/web_agents/agent_type/log directory. To modify its path or its size, configure the AM_SYSTEM_LOG_PATH and AM_SYSTEM_LOG_SIZE environment variables.

The system_n.log file 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.
Agent notifications.

The default value of the AM_SYSTEM_LOG_LEVEL variable is Error. Increase it to Message or All for fine-grained detail.

Valid values for the variable are:

All
Message
Warning
Error
Info

AM_SYSTEM_LOG_PATH

The directory where the system_n.log file is stored.

By default, this environment variable is configured to /path/to/web_agents/agent_type/log.

AM_SYSTEM_LOG_SIZE

Thesize, in bytes, of the /path/to/web_agents/agent_type/log/system_n.log file.

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).

AM_SYSTEM_PIPE_DIR

(Unix only) Thedirectory where the agent instances will store their temporary pipe files.

The default is /path/to/web_agents/agent_type/log/.

Web Agent Installer Environment Variables

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 instance.

AM_PROXY_HOST

When AM and the agent communicate through a proxy configured in forward proxy mode, this environment variable specifies the proxy FQDN.

AM_PROXY_PASSWORD

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.

AM_PROXY_USER

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.

AM_PROXY_PORT

When AM and the agent communicate through a proxy configured in forward proxy mode, this variable specifies the proxy port number.

APACHE_RUN_USER

The user running the Apache HTTP or IBM HTTP Server.

Use this variable if there is no Apache user defined in the httpd.conf file.

APACHE_RUN_GROUP

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 httpd.conf file.

AM_SSL_SCHANNEL

(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.

AM_SSL_KEY

(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_CERT environment variable. For example, /opt/certificates/client-private-key.pem or C:\Certificates\client-private-key.pem.

AM_SSL_PASSWORD

(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_KEY variable. Configure this variable only if the private key is password-protected.

To obfuscate the password, use the agentadmin --p command. For example:

Unix
Windows

$ /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=

AM_SSL_CIPHERS

(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.

For example, HIGH:MEDIUM.

AM_SSL_CERT

When AM is configured to perform client authentication, this environment variable specifies a PEM file that contains the certificate chain for the agent.

For example, /opt/certificates/client-cert.pem, C:\Certificates\client-cert.pem (Windows with OpenSSL), or Cert:\LocalMachine\My location (Windows with the Windows Secure Channel API).

AM_SSL_CA

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, /opt/certificates/ca.pem, C:\Certificates\ca.pem (Windows with OpenSSL), or Cert:\LocalMachine\Ca (Windows with the Windows Secure Channel API).

agentadmin Command

The agentadmin command manages Web Agent installation. It returns EXIT_SUCCESS (or 0) when it completes successfully, and EXIT_FAILURE (or a code greater than zero) when it fails.

The following options are supported:

--i

Install a new agent instance.

Usage: agentadmin --i

--s

Silently, non-interactively, install a new agent instance.

Usage: agentadmin --s web-server-config-file openam-url agent-url realm agent-profile-name agent-profile-password [--changeOwner] [--acceptLicense] [--forceInstall]

web-server-config-file

(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 agentadmin.exe --n.

openam-url

The full URL of the AM instance that the agent will use. Ensure the deployment URI is specified.

Example: https://openam.example.com:8443/openam

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.

agent-url

Enter the full URL of the server on which the agent is running.

Example: http://www.example.com:80

realm

Enter the AM realm containing the agent profile.

agent-profile-name

The name of the agent profile in AM.

agent-profile-password

The full path to the agent profile password file.

--changeOwner

(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 agentadmin command as the root user or using the sudo command.

If you cannot run the agentadmin as the root user or using the sudo command, you must change the ownership manually.

--acceptLicense

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 --acceptLicence parameter. Specifying this options indicates that you have read and accepted the terms stated in the license.

To view the license agreement, open /path/to/web_agents/agent_type/legal/Forgerock_License.txt .

--forceInstall

Add this option to proceed with a silent installation even if it cannot connect to the specified AM server during installation, rather than exiting.

--n

(IIS web agent only) List the sites available in an IIS server.

Example:

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

--l

List existing configured agent instances.

Usage: agentadmin --l

Example:

$ ./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

--g

(IIS web agent only) Remove all web agent instances and libraries from an IIS installation.

Usage: agentadmin.exe --g

For more information, see To Remove Web Agents from IIS.

--e

(IIS web agent only) Enable an existing agent instance.

Usage: agentadmin.exe --e agent-instance

For more information, see To Disable and Enable Web Agents.

--d

(IIS web agent only) Disable an existing agent instance.

Usage: agentadmin.exe --d agent-instance

For more information, see To Disable and Enable Web Agents.

--o

(IIS web agent only) Modify Access Control Lists (ACLs) for files and folders related to a web agent instance.

Usage: agentadmin.exe --o "identity_or_siteID" "directory" [--siteId]

Usage: agentadmin.exe --o "directory" --addAll --removeAll

"identity_or_siteID"

Specifies the identity to be added to the directory’s ACLs. When used with the --siteId option, it specifies an IIS site ID.

"directory"

Specifies the directory that would be modified.

[--siteId]

Specifies that the agentadmin should use identity_or_siteID as an IIS site ID.

--addAll

Add all IIS application pool identities to the directory’s ACLs. This option is not compatible with the --removeAll option.

--removeAll

Remove all IIS application pool identities from the directory’s ACLs. This option is not compatible with the --addAll option.

Examples:

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

--r

Remove an existing agent instance.

Usage: agentadmin --r agent-instance

agent-instance: The ID of the web agent configuration instance to remove.

Respond yes when prompted to confirm removal.

On IIS web agents, the --r option 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 --g option instead.

--k

Generate a new signing key.

Usage: agentadmin --k

Examples:

Unix
Windows

$ cd /web_agents/apache24_agent/bin/$ ./agentadmin --k
Encryption key value: YWM0OThlMTQtMzMxOS05Nw==

C:\> cd web_agents\apache24_agent\bin
C:\web_agents\apache24_agent\bin> agentadmin --k
Encryption key value: YWM0OThlMTQtMzMxOS05Nw==

--p

Use a generated encryption key to encrypt a new password.

Usage: agentadmin --p encryption-key password

encryption-key

An encryption key, generated by the agentadmin --k command.

password

The password to encrypt.

Examples:

Unix
Windows

$ ./agentadmin --p "YWM0OThlMTQtMzMxOS05Nw==" "cat newpassword.file"
Encrypted password value: 07bJOSeM/G8ydO4=

C:\path\to\web_agents\apache24_agent\bin> agentadmin.exe --p "YWM0OThlMTQtMzMxOS05Nw==" "newpassword"
Encrypted password value: 07bJOSeM/G8ydO4=

--V[i]

Validate an agent instance.

Usage:

agentadmin --V[i] agent_instance [user name] [password file] [realm]

[i]

(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.

agent_instance

(Required) The agent instance where to run the validation tests. For example, agent_1.

user name

(Optional) A user ID that exists in the AM server. Required only for the validate_session_profile test. For example, demo.

password file

(Optional) A file containing the password of the user ID used for the validate_session_profile test. For example, /tmp/passwd.txt

realm

(Optional) The realm of the user ID used for the validate_session_profile test. For example, /customers

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 --Vi flag. 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, run the agentadmin --V[i] validator command as the same user that runs the web server.

For example, to use the Apache HTTP Server daemon user:

$ sudo -u daemon ./bin/agentadmin --V agent_1

Running the command as a different user may cause the log/system_0.log and log/monitor_0.pipe files 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

Make sure the user running the command has execute permission on the following directories:

/web_agents/apache24_agent/instances/agent_nnn
/web_agents/apache24_agent/log

Example:

$ ./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.

--v

Display information about agentadmin build and version numbers, and available system resources.

For example:

AM Web Agent for IIS Server 7.5, 8.x
Version: 5.9.1
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).

Configuring Apache HTTP Server as a Reverse Proxy Example

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.

Simplified diagram showing a reverse proxy configuration between AM and the agent.

Figure 1. Reverse Proxy Configured Between the Agent and AM

For information about how to configure Apache for load balancing, and other requirements for your environment, see the Apache documentation.

Locate the httpd.conf file 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

The mod_proxy_wstunnel.so module is required to support the WebSocket protocol used for communication between AM and the agents.

Add the proxy configuration inside the VirtualHost context. 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>
```
⁽¹⁾ RequestHeader: Set to https or 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 goto parameter for redirecting back to the agent after authentication.

⁽²⁾ ProxyPass: Set to allow WebSocket traffic between AM and the agent. If HTTPS is configured between the proxy and AM, set to use the wss protocol instead of ws.

⁽³⁾ ProxyPass: Set to allow HTTP traffic between AM and the agent.

⁽⁴⁾ ProxyPassReverseCookieDomain: Set to rewrite the domain string in `Set-Cookie`headers in the format internal domain (AM’s domain) public domain (proxy’s domain).

⁽⁵⁾ ProxyPassReverse: Set to the same value configured for the ProxyPass directive.

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

Web Policy Agents 5.9.1

Reference

Environment Variables

Web Agent Installer Environment Variables

agentadmin Command

Configuring Apache HTTP Server as a Reverse Proxy Example