Web Agents 2023.11.1

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, refer to Installation environment variables.

For information about allowing environment variables to be used in NGINX, refer to 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

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_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 /path/to/web_agents/agent_type/log/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 /path/to/web_agents/agent_type/log/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 /path/to/web_agents/agent_type/log/system_n.log file.

Default: /path/to/web_agents/agent_type/log/system_n.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/