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

Parameter Definition Default Value

paa_property_files

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

$NGINX/paa/agent.properties

paa_enabled on|off

Value that turns the agent on or off. This property applies to server blocks within the nginx server to control which server blocks are protected by the agent.

off

paa_upstream

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

pingaccess-policy-server

paa_upstream_max_response_header_size

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

4096

paa_thread_pool

Defines the thread pool to use for blocking operations performed by the agent. Currently this only includes policy cache lookup operations when using the ZeroMQ multiprocess policy cache.

default
Note:

You do not have to make any changes to http.conf if the steps in the Installation section were followed.

Changes to the paa_upstream will impact how the agent communicates with PingAccess. Incorrect changes might lead to a non-functional agent.

The configured agent.properties files can contain the following parameters.

The 'upstream pingaccess-policy-server' contains the directive 'pingaccess_servers'. This directive indicates that the servers for the containing upstream are defined by the agent.properties file. The agent only allows this directive to be specified for a single upstream.

Parameter Definition Default Value

agent.engine.configuration.scheme

The URI scheme used to connect to the engine node. Valid values are http and https.

https

agent.engine.configuration.host

The PingAccess hostname.

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

agent.engine.configuration.port

The port the agent connects to on the PingAccess host. This value is defined in the PingAccess run.properties file.

Defined in the PingAccess Admin UI

agent.engine.configuration.username

The unique agent name that identifies the agent in PingAccess.

Defined in the PingAccess Admin UI

agent.engine.configuration.shared.secret

The password used to authenticate the agent to the engine.

Defined in the PingAccess Admin UI

agent.engine.configuration.bootstrap.truststore
The base64-encoded public certificate used to establish HTTPS trust by the agent to the PingAccess engine.
Note:

If you are having difficulty connecting an agent to the PingAccess engine, verify that the Agent Trusted Certificate has been configured correctly in Agent Management.

Generated by PingAccess

agent.engine.configuration.maxConnections

The number of connections a single web server worker process maintains to the PingAccess engine defined in the agent.engine.configuration.host parameter.

10

agent.engine.configuration.timeout

The maximum time (in milliseconds) a request to PingAccess can take from the agent. If this time is exceeded, the client receives a generic 500 Server Error response.

30000

agent.engine.configuration.connectTimeout

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

30000

agent.cache.missInitialTimeout

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

5

agent.cache.broker.publisherPort

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

3031

agent.cache.broker.subscriberPort

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.

3032
agent.cache.maxTokens

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

0

agent.cache.disabled
Determines whether caching of policy decisions 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. This option might be desired when using PingAccess 3.1 or earlier with the following rule types:
  • Groovy script Rule
  • HTTP request Rule
  • Network range Rule
  • Time range Rule
PingAccess 3.2 and later does not require the cache be disabled in order to process these rules correctly from an agent.
Warning:

Disabling caching has a significant impact on the scalability of the PingAccess policy servers, as every rule evaluation is processed by the policy server. Only use this option as a last resort because of the performance penalty.

0

agent.engine.configuration.failover.hosts
The hostname and port of the PingAccess server where the agent should send requests in the event of a failover from the PingAccess Host.
Note:

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 name 'pa.nginx', set the upstream name to upstream pa.nginx.

Defined in the PingAccess Admin UI

agent.engine.configuration.failover.failedRetryTimeout

Seconds before retrying a failed PingAccess server.

60

agent.engine.configuration.failover.MaxRetries

The maximum number of retries before considering a PingAccess server unavailable.

2

agent.cache.type
Controls the type of policy cache used by the agent. There are three valid values for this property:
AUTO
The AUTO cache type 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.
STANDALONE
The STANDALONE cache type does not share policy cache entries across worker processes.
ZMQ
The ZMQ cache type allows the agent to share policy cache entries across all worker processes using ZeroMQ for inter-process communication.

AUTO
agent.send.inventory

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:

v
The PingAccess agent version.
t

The type of PingAccess agent retrieved using the NGINX_VER_BUILD macro.

h

The hostname of the PingAccess agent retrieved using the Server Name directive.

For more information, see Agent inventory logging.

true
agent.inventory

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

The following syntax is used.

agent.inventory=exampleheader=TEST;exampleheader2=TEST2;
Note:

The specified header fields are case-sensitive.

Not present by default.

Add comments to the agent.properties files if necessary. Lines beginning with the # or ! characters are ignored by the agent.

Changes to the agent.properties file require a restart of the web server.

Tip:

See Agent Tuning in the PingAccess Performance tuning reference guide for a discussion on improving agent performance.