--- title: Environment variables description: Configure environment variables to affect the user that is running the web server, virtual host, or location that the agent protects. component: web-agents version: 2025.11 page_id: web-agents:user-guide:configure-envvars canonical_url: https://docs.pingidentity.com/web-agents/2025.11/user-guide/configure-envvars.html --- # 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](../installation-guide/installer-env-vars.html). You can find details about allowing environment variables to be used in NGINX in [env directive](http://nginx.org/en/docs/ngx_core_module.html#env) 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, if another agent instance starts, an error is logged and the agent won't protect any 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`: The agent downloads all policies from AM at startup. 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. * `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](../properties-reference/org.forgerock.agents.config.tls.keylog.enable.html) property or the [AM\_SSL\_KEYLOG\_ENABLE](../installation-guide/installer-env-vars.html#am-ssl-keylog-enable) installation environment variable must also be configured to enable TLS key logging. Learn more in [TLS key logging](../maintenance-guide/troubleshooting.html#tls-key-logging). * `AM_SSL_OPTIONS` Overrides the default SSL/TLS protocols for the agent, set in the [Security Protocol List](../properties-reference/org.forgerock.agents.config.tls.html) 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: * `TLSv1` * `TLSv1.1` * `TLSv1.2` (Enabled) * `TLSv1.3` (Enabled) For example, to configure `TLSv1.1`, set the environment variable to `AM_SSL_OPTIONS = -TLSv1 -TLSv1.2 -TLSv1.3`. * `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](#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/`