Web Agents 2024.11

Installation environment variables

This section describes Web Agent properties that are configured by environment variables and set during installation.

Use installation environment variables as follows:

  • Add environment variables to the command line when you install the agent. For example:

    • Linux

    • Windows

    $ AM_AGENT_AUTH_MODE=1 ./agentadmin --i
    C:\>set AM_AGENT_AUTH_MODE=1
C:\>agentadmin.exe --i agent_1

  • Use installation environment variables with the agentadmin -V[i] command to validate the installation with different parameters. For example:

    • Linux

    • Windows

    $ AM_PROXY_HOST=proxy.host.net AM_PROXY_PORT=8080 AM_PROXY_USER=user AM_PROXY_PASSWORD=pass ./agentadmin --Vi
    C:\>set AM_PROXY_HOST=proxy.host.net
C:\>set AM_PROXY_PORT=8080
C:\>set AM_PROXY_USER=user
C:\>set AM_PROXY_PASSWORD=pass
C:\>agentadmin.exe --Vi agent_1

You can find details about other environment variables in Environment variables.

AM_AGENT_AUTH_MODE

A flag to determine which method the agent uses to authenticate to Advanced Identity Cloud and AM:

  • 0 (default): The agent authenticates using the Agent journey, but falls back to using the deprecated authentication module if authentication fails.

    If you use PingAM 7.3 or 7.4 and experience issues with session quotas, set this environment variable to 2 to always authenticate using the authentication module.

  • 1: The agent always authenticates using the Agent journey. If this fails, the agent doesn’t try to authenticate using the authentication module.

    This is the recommended setting. Make sure the Agent journey exists. Learn more in Authenticate agents to the identity provider.

  • 2: The agent always authenticates using the authentication module. Modules are deprecated and will be removed in a future release.

AM_PROXY_HOST

The proxy FQDN, when AM and the agent communicate through a proxy configured in forward proxy mode.

AM_PROXY_PASSWORD

The agent 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.

AM_PROXY_USER

The agent username, 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.

AM_PROXY_PORT

The proxy port number, when AM and the agent communicate through a proxy configured in forward proxy mode.

AM_SSL_KEYLOG_ENABLE

A flag to enable TLS key logging during the agent installation process:

  • 0 (default): Disable TLS key logging.

  • 1: Enable TLS key logging to troubleshoot TLS issues between the agent and AM.

    If you enable TLS key logging, you must specify the name of the SSL key log file in the AM_SSL_KEYLOG_FILE environment variable.

    Only enable TLS key logging when advised by Support. After troubleshooting, disable key logging and remove the SSL key log file.

Learn more in TLS key logging.

APACHE_RUN_USER

The user running the Apache HTTP or IBM HTTP Server. Set this variable before installation when an Apache user is not defined in httpd.conf. This can be the case in non-Red Hat Enterprise Linux-based distributions.

APACHE_RUN_GROUP

The group to which the user running the Apache HTTP Server or IBM HTTP Server belongs. Set this variable before installation when an Apache group is not defined in httpd.conf. This can be the case in non-Red Hat Enterprise Linux-based distributions.

AM_SSL_SCHANNEL

Use for Windows only, when TLS/SSL is configured in AM or the agent web server.

A flag for whether the agent installation process should use the Windows Secure Channel API:

  • 0: Disable Windows Secure Channel API support. The agent uses 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

Use for OpenSSL only, when TLS/SSL is configured in AM or the agent web server.

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:

  • Unix

  • Windows

/opt/certificates/client-private-key.pem
C:\Certificates\client-private-key.pem
AM_SSL_PASSWORD

Use for OpenSSL only, when TLS/SSL is configured in AM or the agent web server.

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:

  • Unix

  • Windows

$ /path/to/web_agents/agent_type/bin/> agentadmin --p "Encryption Key" “cat certificate_password.file”

Encrypted password value: zck...jtc=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

Use for OpenSSL only, when TLS/SSL is configured in AM or the agent web server.

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 at http://www.openssl.org.

For example, HIGH:MEDIUM.

AM_SSL_CERT

Use when TLS/SSL is configured in AM or the agent web server.

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