The /etc/httpd/conf.d/paa.conf file contains the configuration options defined in the following table.

/etc/httpd/conf.d/paa.conf configuration options
/etc/httpd/conf.d/paa.conf configuration options
Parameter Definition Default Value

PaaCertificateDir

String value containing the path to the certificates extracted from the .properties files.

conf.d

PaaEnabled

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

This value can be set globally; set for individual virtual hosts, directories, locations, or files; or both. The agent follows the most specific value that you set.

Note:

If you disable the PaaEnabled parameter globally, ensure that the PaaEnabled directive is set to on for the PingAccess reserved application context root. This is /pa by default.

For example, adding this text to an included configuration file enables PingAccess for the /pa context root and for the /var/www/html/one directory:

<VirtualHost *:81>
    <Location /pa>
        PaaEnabled on
    </Location>
    <Directory "/var/www/html/one">
        PaaEnabled on
    </Directory>
</VirtualHost>

Adding this text to an included configuration file disables PingAccess for all content in the /var/www/html/two directory except for files named page2.html:

<VirtualHost *:81>
    <Directory "/var/www/html/two">
        PaaEnabled off
       <Files "page2.html">
            PaaEnabled on
       </Files>
    </Directory>
</VirtualHost>

on

PaaPropertyFiles

List of .properties files that store configuration data used to connect the agent to the PingAccess engine nodes that the agent will communicate with.

conf.d/agent.properties

PaaEnabledNoteName

An optional parameter which defines a note name. If a request includes a note with this name and a value of on or off, this value overrides the PaaEnabled setting for that request.

If you want to use this feature, you must deploy a custom module to include this note with the correct value.

paa-enabled-note

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

agent.properties configuration options
agent.properties configuration options
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 host name.

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

agent.engine.configuration.port

The port that 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're having difficulty connecting an agent to the PingAccess engine, verify that the Agent Trusted Certificate is configured correctly in Agent Management.

Generated by PingAccess

agent.engine.configuration.maxConnections

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

10

agent.engine.configuration.timeout

The maximum amount of time, in milliseconds, that 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 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.

30000

agent.cache.missInitialTimeout

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.

5

agent.cache.broker.publisherPort

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.

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

Warning:

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

0

agent.engine.configuration.failover.hosts

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.

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

Defined in the PingAccess Admin UI

agent.engine.configuration.failover.failedRetryTimeout

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

60

agent.engine.configuration.failover.MaxRetries

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.

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 there's only one worker process, the agent uses the STANDALONE cache. If there are two or more worker processes, the agent uses the ZMQ cache.
STANDALONE
The STANDALONE cache type doesn't 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 ap_get_server_description function.

h

The host name of the PingAccess agent retrieved using the ServerName directive.

For more information, see Agent inventory logging.

true

agent.inventory

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

This parameter uses the following syntax:

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

The specified header fields are case-sensitive.

Not present by default.

agent.apache.host.source.headerName

If present, specifies a header that overrides the default X-Forwarded-Host header. This header communicates the authority component of the effective request URL on the protected application.

Not present by default.
Tip:

You can 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.

For more information on how to improve agent performance, see the Performance Tuning Guide.