The $NGINX/paa/http.conf file contains the configuration options defined in the following table.

$NGINX/paa/http.conf configuration options
$NGINX/paa/http.conf configuration options
Parameter Definition Default Value


Properties file that stores configuration data used to connect the agent to the PingAccess engine nodes.



Determines whether the agent is enabled or disabled for a specific server configuration. Valid values are on or off.

To control which blocks that the agent protects, you can set the paa_enabled parameter on:

  • Specific server blocks within the NGINX server
  • Specific location blocks

For example, if you want to set up an unprotected passthrough resource that PingAccess should always allow access to, you can set paa_enabled to off in the location block that represents the unprotected resource. This expedites request processing because the agent doesn't need to request a decision from the PingAccess engine.


You can apply this parameter globally to the http block. The agent follows the most specific value that you set.

If you set the paa_enabled parameter to off globally, ensure that the paa_enabled parameter is set to on for the PingAccess reserved application context root. By default, this context root is /pa.



Defines the upstream that the PingAccess agent uses to route policy decision requests to PingAccess policy servers.



Defines the maximum size of the response header, in bytes, that the PingAccess agent can receive from a PingAccess policy server.



Defines the thread pool to use for blocking operations performed by the agent.


This only includes policy cache lookup operations when using the ZeroMQ multiprocess policy cache.


  • You do not have to make any changes to http.conf if you followed the PingAccess agent for NGINX Installation steps.
  • Changes to the paa_upstream parameter will impact how the agent communicates with PingAccess. Incorrect changes might lead to a non-functional agent.
  • The upstream pingaccess-policy-server contains the directive pingaccess_servers. This directive indicates that the servers for the containing upstream are defined by the file. The agent only allows this directive to be specified for a single upstream.

The configured files can contain the following properties:

Property Definition Default Value


The URI scheme used to connect to the engine node. Acceptable values are:

  • http
  • https


The PingAccess host name.

The value in the agent node's PingAccess Host field.


The port that the agent connects to on the PingAccess host.


This value is defined in the PingAccess file.

Defined in the PingAccess admin console


The unique agent name that identifies the agent in PingAccess.

Defined in the PingAccess admin console


The password which is used to authenticate the agent to the engine.

Defined in the PingAccess admin console


The base64-encoded public certificate which is used to establish HTTPS trust by the agent to the PingAccess engine.


If you are having difficulty connecting an agent to the PingAccess engine, complete the following steps to verify that the Agent Trusted Certificate is configured correctly:

  1. Base64 decode the public certificate into a .crt file and review the contents.
  2. In the PingAccess server, make sure that the agent HTTP listener is using the matching private key. Learn more in Assigning key pairs

Generated by PingAccess


The number of connections that a single web server worker process maintains to the PingAccess engine defined in the property.



The maximum amount of time, in milliseconds, that an agent request made to PingAccess can take. If this time is exceeded, the client receives a generic 500 Server Error response.



The maximum amount of time, in milliseconds, that the agent can take to connect to the PingAccess engine. If this time is exceeded, the client receives a generic 500 Server Error response.



The maximum amount of time (in milliseconds) that a web server worker process waits for a response to a policy cache request sent to other web server worker processes.


The network port that web server processes use to publish policy cache requests to other web server worker processes. This port is bound to the localhost network only.


The network port that web server processes use to receive policy cache requests from other web server worker processes. This port is bound to the localhost network only.



The maximum number of tokens that are stored in the policy cache for a single web server worker process. A value of 0 means there is no maximum.



Determines whether policy decision caching is enabled or disabled. A value of 1 disables caching, forcing the agent to communicate with the PingAccess host any time a policy decision needs to be made.

You might want to use this option for custom rules created using the PingAccess SDK that involve data that changes with every request within a resource and session.


Disabling caching has a significant impact on the scalability of the PingAccess policy servers, as every rule evaluation is processed by the policy server. Because of the performance penalty, only use this option if necessary.



The host name and port of the PingAccess server where the agent should send requests in the event of a failover from the PingAccess host.


If this parameter is set, the upstream block name in $NGINX/paa/http.conf needs to be modified to a name that will be found in the certificate associated with the PingAccess agent HTTPS listener.

For example, if your PingAccess certificate contains the name pa.nginx, set the upstream name to upstream pa.nginx.

Defined in the PingAccess admin console


The number of seconds to wait before the agent should retry connecting to a failed PingAccess server.



The number of times to retry a connection to a PingAccess server after an unsuccessful attempt. If all retries fail, the agent marks the PingAccess server as failed for the duration of the agent.engine.configuration.failover.failedRetryTimeout value and tries another PingAccess server if one is available.



Controls the type of policy cache used by the agent. There are three acceptable values for this property:

Determines the appropriate cache to use based on the number of worker processes. If the number of worker processes is 1, the agent uses the STANDALONE cache. If the number of worker processes is 2 or more, the agent uses the ZMQ cache.
Does not share policy cache entries across worker processes.
Allows the agent to share policy cache entries across all worker processes using ZeroMQ for inter-process communication.



Determines whether the vnd-pi-agent agent inventory header is sent along with each request to the PingAccess policy server.

This header contains the following fields:

The PingAccess agent version.
The type of PingAccess agent retrieved using the NGINX_VER_BUILD macro.
The host name of the PingAccess agent retrieved using the ServerName directive.

Learn more in Agent inventory logging.



Specifies additional values to include in the vnd-pi-agent agent inventory header.

This property uses the following syntax:


The specified header fields are case-sensitive.

This property isn't present by default.


You can add comments to the files if necessary. The agent ignores lines beginning with the # or ! characters.


If you make changes to the file, you must restart the web server.


Learn more about improving agent performance in the Performance tuning guide.