Web Policy Agents 5.10

Environment variables

Configure environment variables to affect the user that is running the web server, virtual host, or location that the agent protects.

This section describes Web Agent properties that are configured by environment variables. After setting an environment variable, restart Web Agent.

For information about environment variables for installation, see Installation environment variables.

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.

Default: 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.

When the maximum is reached, an additional agent instances that starts will log an error, and will not protect resources.

Default: 32

AM_MAX_SESSION_CACHE_SIZE

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

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

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.

Allowed values:

  • 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 0022 and the AM_RESOURCE_PERMISSIONS is 0666. The agent runtime resources 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 0002 and AM_RESOURCE_PERMISSIONS is 0666. The files are created with 664 permissions, which allows them 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.

Supported protocols:

  • 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 web server. The logs are written to the system_n.log file, where n indicates the agent group number.

Consider an environment with two Apache HTTP 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:

  • All

  • Message

  • Warning

  • Error

  • Info

AM_SYSTEM_LOG_PATH

The directory where the system_n.log file is stored.

Default: /path/to/web_agents/agent_type/log

AM_SYSTEM_LOG_SIZE

The size in bytes of the /path/to/web_agents/agent_type/log/system_n.log file.

Valid range: 0 (unlimited log file size) to 4294967295 bytes (4GB)

Default: 0

AM_SYSTEM_PIPE_DIR

(Unix only) The directory where agent instances store temporary pipe files.

Default: /path/to/web_agents/agent_type/log/

Copyright © 2010-2022 ForgeRock, all rights reserved.