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.

You can find details about environment variables for installation in Installation environment variables.

You can find details about allowing environment variables to be used in NGINX in 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

Policy evaluation mode (AM_POLICY_CACHE_MODE)

Policy evaluation mode:

off or 0 (default): When a request requires a policy decision, the agent contacts AM for the decision.
on or 1: The agent downloads all policies from AM at start up. When a request requires a policy decision, the agent uses the downloaded policies to make the policy decision.

In both modes, the agent caches the policy decision. If a request requires the same policy decision again, the agent uses the cached decision.

(Optional) Use the AM_POLICY_CACHE_DIR environment variable to specify a directory in which to store the policy cache.

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_KEYLOG_FILE

The name of the SSL key log file. For example, /tmp/keylog.log. Ensure the agent has write access to this file.

The Enable TLS key logging property or the AM_SSL_KEYLOG_ENABLE installation environment variable must also be configured to enable TLS key logging.

Learn more in TLS key logging.

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 won’t 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 for messages from the agent startup and background processes. Messages provide information about the agent initialisation, local files that the agent uses, or resources that the agent uses.

By default, messages are written to the file given by AM_SYSTEM_LOG_PATH, by default /path/to/web_agents/agent_type/log/system_n.log.

The value n in the system_n.log file indicates the agent group number. Consider an environment with the following 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 write to the system_0.log file.
Apache_2 has one agent instance configured, agent_3, with AmAgentId set to 1. The instance write to the system_1.log file.

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 following case-insensitive values are valid:

All
Message
Warning
Error (default)
Info

AM_SYSTEM_LOG_PATH: The full path and filename to the system_n.log file.

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

AM_SYSTEM_LOG_FILES: The maximum number of rotated system_n.log files that the agent stores.

Default: 0
AM_SYSTEM_LOG_SIZE: The maximum size in bytes of the 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/

Web Agents 2024.9

Environment variables