Install from NGINX Plus repo

Note:

If you are using NGINX One Console to manage your NGINX instances, NGINX Agent is installed automatically when you add an NGINX instance to NGINX One Console.

For a quick guide on how to connect your instance to NGINX One Console see: Connect to NGINX One Console

Overview

Follow the steps in this guide to install NGINX Agent in your NGINX instance using the NGINX Plus repository.

Before you begin

  • You must use one of the supported operating system and architectures
  • The user running the NGINX Agent installation must have the same privileges as the main NGINX process. We recommend not running NGINX or NGINX Agent as the root user.

Manual installation using the NGINX Plus repository

Before you install NGINX Agent for the first time on your system, you need to set up the nginx-agent packages repository. Afterward, you can install and update NGINX Agent from the repository.

Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux

Install NGINX Agent on RHEL, CentOS, Rocky Linux, AlmaLinux, and Oracle Linux

  1. Create the /etc/ssl/nginx directory:

    sudo mkdir -p /etc/ssl/nginx

  2. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

  4. Install the prerequisites:

    sudo yum install yum-utils procps

  5. Set up the yum repository by creating the file nginx-agent.repo in /etc/yum.repos.d, for example using vi:

    sudo vi /etc/yum.repos.d/nginx-agent.repo

  6. Add the following lines to nginx-agent.repo:

    [nginx-agent]
name=nginx agent repo
baseurl=https://pkgs.nginx.com/nginx-agent/centos/$releasever/$basearch/
sslclientcert=/etc/ssl/nginx/nginx-repo.crt
sslclientkey=/etc/ssl/nginx/nginx-repo.key
gpgcheck=0
enabled=1

  7. To install nginx-agent, run the following command:

    sudo yum install nginx-agent

    When prompted to accept the GPG key, verify that the fingerprint matches 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, and if so, accept it.

Install NGINX Agent on Ubuntu

Install NGINX Agent on Ubuntu

  1. Create the /etc/ssl/nginx directory:

    sudo mkdir -p /etc/ssl/nginx

  2. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

  4. Install the prerequisites:

    sudo apt-get install apt-transport-https lsb-release ca-certificates wget gnupg2 ubuntu-keyring

  5. Download and add NGINX signing key:

    wget -qO - https://cs.nginx.com/static/keys/nginx_signing.key | gpg --dearmor | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

  6. Create apt configuration /etc/apt/apt.conf.d/90pkgs-nginx:

    Acquire::https::pkgs.nginx.com::Verify-Peer "true";
Acquire::https::pkgs.nginx.com::Verify-Host "true";
Acquire::https::pkgs.nginx.com::SslCert     "/etc/ssl/nginx/nginx-repo.crt";
Acquire::https::pkgs.nginx.com::SslKey      "/etc/ssl/nginx/nginx-repo.key";

  7. Add the nginx-agent repository:

    echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://pkgs.nginx.com/nginx-agent/ubuntu/ `lsb_release -cs` agent" \
| sudo tee /etc/apt/sources.list.d/nginx-agent.list

  8. To install nginx-agent, run the following commands:

    sudo apt update
sudo apt install nginx-agent
Install NGINX Agent on Debian

Install NGINX Agent on Debian

  1. Create the /etc/ssl/nginx directory:

    sudo mkdir -p /etc/ssl/nginx

  2. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

  4. Install the prerequisites:

    sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring

  5. Add the nginx-agent repository:

    echo "deb https://pkgs.nginx.com/nginx-agent/debian/ `lsb_release -cs` agent" \
| sudo tee /etc/apt/sources.list.d/nginx-agent.list

  6. Create apt configuration /etc/apt/apt.conf.d/90pkgs-nginx:

    Acquire::https::pkgs.nginx.com::Verify-Peer "true";
Acquire::https::pkgs.nginx.com::Verify-Host "true";
Acquire::https::pkgs.nginx.com::SslCert     "/etc/ssl/nginx/nginx-repo.crt";
Acquire::https::pkgs.nginx.com::SslKey      "/etc/ssl/nginx/nginx-repo.key";

  7. To install nginx-agent, run the following commands:

    sudo apt update
sudo apt install nginx-agent
Install NGINX Agent on SLES

Install NGINX Agent on SLES

  1. Create the /etc/ssl/nginx directory:

    sudo mkdir -p /etc/ssl/nginx

  2. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

  4. Create a file bundle of the certificate and key:

    cat /etc/ssl/nginx/nginx-repo.crt /etc/ssl/nginx/nginx-repo.key > /etc/ssl/nginx/nginx-repo-bundle.crt

  5. Install the prerequisites:

    sudo zypper install curl ca-certificates gpg2 gawk

  6. To set up the zypper repository for nginx-agent packages, run the following command:

    sudo zypper addrepo --refresh --check \
   'https://pkgs.nginx.com/nginx-agent/sles/$releasever_major?ssl_clientcert=/etc/ssl/nginx/nginx-repo-bundle.crt&ssl_verify=peer' nginx-agent

  7. Next, import an official NGINX signing key so zypper/rpm can verify the package’s authenticity. Fetch the key:

    curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key

  8. Verify that the downloaded file contains the proper key:

    gpg --with-fingerprint --dry-run --quiet --no-keyring --import --import-options import-show /tmp/nginx_signing.key

  9. The output should contain the full fingerprint 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62 as follows:

    pub   rsa2048 2011-08-19 [SC] [expires: 2024-06-14]
   573B FD6B 3D8F BC64 1079  A6AB ABF5 BD82 7BD9 BF62
uid                      nginx signing key <signing-key@nginx.com>

  10. Finally, import the key to the rpm database:

    sudo rpmkeys --import /tmp/nginx_signing.key

  11. To install nginx-agent, run the following command:

    sudo zypper install nginx-agent
Install NGINX Agent on Alpine Linux

Install NGINX Agent on Alpine Linux

  1. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  2. Copy the files to the /etc/apk/ directory:

    sudo cp nginx-repo.key /etc/apk/cert.key
sudo cp nginx-repo.crt /etc/apk/cert.pem

  3. Install the prerequisites:

    sudo apk add openssl curl ca-certificates

  4. To set up the apk repository for nginx-agent packages, run the following command:

    printf "%s%s%s\n" \
   "https://pkgs.nginx.com/nginx-agent/alpine/v" \
   `grep -o -E '^[0-9]+\.[0-9]+' /etc/alpine-release` \
   "/main" \
   | sudo tee -a /etc/apk/repositories

  5. Next, import an official NGINX signing key so apk can verify the package’s authenticity. Fetch the key:

    curl -o /tmp/nginx_signing.rsa.pub https://nginx.org/keys/nginx_signing.rsa.pub

  6. Verify that downloaded file contains the proper key:

    openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -text -noout

    The output should contain the following modulus:

    Public-Key: (2048 bit)
Modulus:
   00:fe:14:f6:0a:1a:b8:86:19:fe:cd:ab:02:9f:58:
   2f:37:70:15:74:d6:06:9b:81:55:90:99:96:cc:70:
   5c:de:5b:e8:4c:b2:0c:47:5b:a8:a2:98:3d:11:b1:
   f6:7d:a0:46:df:24:23:c6:d0:24:52:67:ba:69:ab:
   9a:4a:6a:66:2c:db:e1:09:f1:0d:b2:b0:e1:47:1f:
   0a:46:ac:0d:82:f3:3c:8d:02:ce:08:43:19:d9:64:
   86:c4:4e:07:12:c0:5b:43:ba:7d:17:8a:a3:f0:3d:
   98:32:b9:75:66:f4:f0:1b:2d:94:5b:7c:1c:e6:f3:
   04:7f:dd:25:b2:82:a6:41:04:b7:50:93:94:c4:7c:
   34:7e:12:7c:bf:33:54:55:47:8c:42:94:40:8e:34:
   5f:54:04:1d:9e:8c:57:48:d4:b0:f8:e4:03:db:3f:
   68:6c:37:fa:62:14:1c:94:d6:de:f2:2b:68:29:17:
   24:6d:f7:b5:b3:18:79:fd:31:5e:7f:4c:be:c0:99:
   13:cc:e2:97:2b:dc:96:9c:9a:d0:a7:c5:77:82:67:
   c9:cb:a9:e7:68:4a:e1:c5:ba:1c:32:0e:79:40:6e:
   ef:08:d7:a3:b9:5d:1a:df:ce:1a:c7:44:91:4c:d4:
   99:c8:88:69:b3:66:2e:b3:06:f1:f4:22:d7:f2:5f:
   ab:6d
Exponent: 65537 (0x10001)

  7. Finally, move the key to apk trusted keys storage:

    sudo mv /tmp/nginx_signing.rsa.pub /etc/apk/keys/

  8. To install nginx-agent, run the following command:

    sudo apk add nginx-agent
Install NGINX Agent on Amazon Linux

Install NGINX Agent on Amazon Linux

  1. Create the /etc/ssl/nginx directory:

    sudo mkdir -p /etc/ssl/nginx

  2. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the nginx-repo.crt and nginx-repo.key files to the /etc/ssl/nginx/ directory:

    sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

  4. Install the prerequisites:

    sudo yum install yum-utils procps ca-certificates

  5. To set up the yum repository for Amazon Linux 2, create a file with name /etc/yum.repos.d/nginx-agent.repo with the following contents:

    [nginx-agent]
name=nginx-agent repo
baseurl=https://pkgs.nginx.com/nginx-agent/amzn2/$releasever/$basearch
sslclientcert=/etc/ssl/nginx/nginx-repo.crt
sslclientkey=/etc/ssl/nginx/nginx-repo.key
gpgcheck=0
enabled=1

  6. To install nginx-agent, run the following command:

    sudo yum install nginx-agent

  7. When prompted to accept the GPG key, verify that the fingerprint matches 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, and if so, accept it.

Install NGINX Agent on FreeBSD

Install NGINX Agent on FreeBSD

  1. Create the /etc/ssl/nginx directory:

    sudo mkdir -p /etc/ssl/nginx

  2. Log in to MyF5 Customer Portal and download your nginx-repo.crt and nginx-repo.key files.

  3. Copy the files to the /etc/ssl/nginx/ directory:

    sudo cp nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

  4. Install the prerequisite ca_root_nss package:

    sudo pkg install ca_root_nss

  5. To setup the pkg repository create a file with name /etc/pkg/nginx-agent.conf with the following content:

    nginx-agent: {
URL: pkg+https://pkgs.nginx.com/nginx-agent/freebsd/${ABI}/latest
ENABLED: yes
MIRROR_TYPE: SRV
}

  6. Add the following lines to the /usr/local/etc/pkg.conf file:

    PKG_ENV: { SSL_NO_VERIFY_PEER: "1",
SSL_CLIENT_CERT_FILE: "/etc/ssl/nginx/nginx-repo.crt",
SSL_CLIENT_KEY_FILE: "/etc/ssl/nginx/nginx-repo.key" }

  7. To install nginx-agent, run the following command:

    sudo pkg install nginx-agent

Manually connect NGINX Agent to NGINX One Console

If you have installed NGINX Agent manually, you will need to connect it to the NGINX One Console to manage your NGINX instances.

  1. Ensure NGINX Agent is installed

  2. Locate the NGINX Agent Configuration File:

    /etc/nginx-agent/nginx-agent.conf

  3. Open the NGINX Agent configuration file in a text editor like vim:

    sudo vim /etc/nginx-agent/nginx-agent.conf

  4. Uncomment the command block, and set the token to your data plane key

  5. Save the changes and close the editor

  6. Restart the NGINX Agent service:

    sudo systemctl stop nginx-agent

Start, stop, and enable NGINX Agent

To start NGINX Agent on systemd systems, run the following command:

sudo systemctl start nginx-agent

To enable NGINX Agent to start on boot, run the following command:

sudo systemctl enable nginx-agent

To stop NGINX Agent, run the following command:

sudo systemctl stop nginx-agent

Verify that NGINX Agent is running

Once you have installed NGINX Agent, you can verify that it is running with the following command:

sudo systemctl status nginx-agent

To check the version installed, run the following command:

sudo nginx-agent -v
Last modified April 16, 2025