---
title: Installing on NGINX
description: Install a PingAccess agent on an NGINX system.
component: pingaccess
version: 9.0
page_id: pingaccess:agents_and_integrations:pa_installing_on_nginx
canonical_url: https://docs.pingidentity.com/pingaccess/9.0/agents_and_integrations/pa_installing_on_nginx.html
revdate: December 8, 2025
section_ids:
  before-you-begin: Before you begin
  steps: Steps
---

# Installing on NGINX

Install a PingAccess agent on an NGINX system.

|   |                                                                                                                                                                                  |
| - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | This procedure assumes your NGINX installation lives at `$NGINX`. Modify the paths this procedure uses based on the location of your NGINX installation and configuration files. |

## Before you begin

* Download an NGINX agent `.zip` file from the [PingAccess Downloads](https://www.pingidentity.com/en/resources/downloads/pingaccess.html) page and extract the contents to the `$PINGACCESS_AGENT_NGINX` directory.

  |   |                                                                                                                                                                                                                                     |
  | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  |   | Amazon Linux 2 systems use RHEL 7 download bundles. Ping Identity will remove support for the last two RHEL 7 download bundles (NGINX Plus R31 and NGINX OSS 1.25.3) when support is added for NGINX Plus R36 and NGINX OSS 1.29.3. |

* The agent RPM has required dependencies that might be available through standard repositories. If these dependencies aren't available in your Linux version, you can install them using the following included packages.

  > **Collapse: Included packages for RHEL 8:**
  >
  > * `libsodium-1.0.18-2.el8.x86_64.rpm`
  >
  > * `libunwind-1.3.1-3.el8.x86_64.rpm`
  >
  > * `openpgm-5.2.122-21.el8.x86_64.rpm`
  >
  > * `zeromq-4.3.4-3.el8.x86_64.rpm`

  > **Collapse: Included packages for RHEL 9:**
  >
  > * `libsodium-1.0.18-8.el9.x86_64.rpm`
  >
  > * `libunwind-1.6.2-1.el9.x86_64.rpm`
  >
  > * `openpgm-5.2.122-28.el9.x86_64.rpm`
  >
  > * `zeromq-4.3.4-2.el9.x86_64.rpm`

* [Configure an agent in the PingAccess admin console.](../pingaccess_user_interface_reference_guide/pa_adding_agents.html)

## Steps

1. To install the NGINX module, run the `yum install pingaccess-agent-nginx-*.rpm lib*.rpm` command.

2. Prepare the `<agent_name>_agent.properties` file:

   1. In the PingAccess admin console, go to **Applications > Agents** and open your configured agent. In the **Shared Secrets** section, click the **Download** icon to download the `<agent_name>_agent.properties` file.

   2. Copy the `<agent_name>_agent.properties` file to `$NGINX/paa/agent.properties`.

   3. If you're installing on NGINX OSS, edit the `<agent_name>_agent.properties` file, setting the `agent.engine.configuration.maxConnections` property to a value of `0`.

3. Make the following modifications to the NGINX configuration file, `$NGINX/nginx.conf`:

   1. To load the PingAccess Agent for NGINX module, add the following directive:

      ```
      load_module modules/ngx_http_paa_module.so;
      ```

   2. To configure the PingAccess Agent for NGINX module, add the following directive in the http {} block:

      ```
      include $NGINX/paa/http.conf;
      ```

      |   |                                                                                                                                                                                                           |
      | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      |   | In the PingAccess [Adding agents](../pingaccess_user_interface_reference_guide/pa_adding_agents.html) procedure, the **PingAccess Host** must match the certificate CN or Subject Alternative Name (SAN). |

4. Make the following modifications to the `$NGINX/paa/http.conf` file:

   1. To enable the PingAccess agent, modify the following property:

      ```
      paa_enabled on;
      ```

      |   |                                                                                                                                                                                                                                                                                                                                                                                                                     |
      | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      |   | If you've set the `agent.engine.configuration.failover.hosts` property in the `agent.properties` file, you must update the `paa_upstream` and upstream blocks in the provided `http.conf` file to a value consistent with a CN or SAN of the certificate associated with the PingAccess Agent HTTPS Listener. Otherwise, you won't be able to establish an HTTPS connection to either the primary or backup server. |

   2. If you're installing on NGINX OSS, comment out the line containing the queue directive.

      For example:

      ```
      # queue 65536;
      ```

5. Restart the NGINX server:

   1. To stop the NGINX server, run the `sudo systemctl stop nginx` command.

   2. To start the NGINX server, run the `sudo systemctl start nginx` command.