Install from Open Source repo

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 Open Source 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 Open Source 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 Alpine Linux

Expand instructions

  1. Install the prerequisites:

    sudo apk add openssl curl ca-certificates

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

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

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

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

    shell
    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)

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

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

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

    sudo apk add nginx-agent

  7. Verify the installation:

    sudo nginx-agent -v

Install NGINX Agent on Amazon Linux

Expand instructions

  1. Install the prerequisites:

    sudo yum install yum-utils procps

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

    ini
    [nginx-agent]
name=nginx agent repo
baseurl=http://packages.nginx.org/nginx-agent/amzn2/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

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

    sudo yum install nginx-agent

    To install nginx-agent with a specific version (for example, 2.42.0):

    sudo yum install -y nginx-agent-2.42.0

  4. When prompted to accept the GPG key, verify that the fingerprint matches 8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46, 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, 9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3, and if so, accept it.

  5. Verify the installation:

    sudo nginx-agent -v

Install NGINX Agent on Debian

Expand instructions

  1. Install the prerequisites:

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

  2. Import an official nginx signing key so apt can verify the packages authenticity. Fetch the key:

    shell
    curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
   | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

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

    shell
    gpg --dry-run --quiet --no-keyring \
--import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg

    The output should contain the full fingerprints 8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46, 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, 9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3 as follows:

    shell
      pub   rsa4096 2024-05-29 [SC]
        8540A6F18833A80E9C1653A42FD21310B49F6B46
  uid                      nginx signing key <[email protected]>

  pub   rsa2048 2011-08-19 [SC] [expires: 2027-05-24]
        573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
  uid                      nginx signing key <[email protected]>

  pub   rsa4096 2024-05-29 [SC]
        9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3
  uid                      nginx signing key <[email protected]>
    Important
    If the fingerprint is different, remove the file.

  4. Add the nginx-agent repository:

    shell
    echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
http://packages.nginx.org/nginx-agent/debian/ `lsb_release -cs` agent" \ | sudo tee /etc/apt/sources.list.d/nginx-agent.list

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

    shell
    sudo apt update
sudo apt install nginx-agent

    To install nginx-agent with a specific version (for example, 2.42.0):

    Update your package index and install a specific version of the nginx-agent. Replace <VERSION_CODENAME> with your current Debian codename (for example, bullseye).

    shell
    sudo apt update
sudo apt install -y nginx-agent=2.42.0~<VERSION_CODENAME>

  6. Verify the installation:

    sudo nginx-agent -v

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

Expand instructions

  1. Install the prerequisites:

    sudo yum install yum-utils

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

    ini
    [nginx-agent]
name=nginx agent repo
baseurl=http://packages.nginx.org/nginx-agent/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

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

    sudo yum install nginx-agent

    To install nginx-agent with a specific version (for example, 2.42.0):

    sudo yum install -y nginx-agent-2.42.0

    When prompted to accept the GPG key, verify that the fingerprint matches 8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46, 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, 9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3, and if so, accept it.

  4. Verify the installation:

    sudo nginx-agent -v

Install NGINX Agent on SLES

Expand instructions

  1. Install the prerequisites:

    sudo zypper install curl ca-certificates gpg2 gawk

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

    shell
    sudo zypper addrepo --gpgcheck --refresh --check \
   'http://packages.nginx.org/nginx-agent/sles/$releasever_major' nginx-agent

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

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

  5. The output should contain the full fingerprints 8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46, 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, 9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3 as follows:

    shell
      pub   rsa4096 2024-05-29 [SC]
        8540A6F18833A80E9C1653A42FD21310B49F6B46
  uid                      nginx signing key <[email protected]>

  pub   rsa2048 2011-08-19 [SC] [expires: 2027-05-24]
        573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
  uid                      nginx signing key <[email protected]>

  pub   rsa4096 2024-05-29 [SC]
        9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3
  uid                      nginx signing key <[email protected]>

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

    sudo rpmkeys --import /tmp/nginx_signing.key

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

    sudo zypper install nginx-agent

    To install nginx-agent with a specific version (for example, 2.42.0):

    sudo zypper install -y nginx-agent=2.42.0

  8. Verify the installation:

    sudo nginx-agent -v

Install NGINX Agent on Ubuntu

Expand instructions

  1. Install the prerequisites:

    sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring

  2. Import an official nginx signing key so apt can verify the packages authenticity. Fetch the key:

    shell
    curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
   | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

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

    gpg --dry-run --quiet --no-keyring --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg

    The output should contain the full fingerprints 8540 A6F1 8833 A80E 9C16 53A4 2FD2 1310 B49F 6B46, 573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62, 9E9B E90E ACBC DE69 FE9B 204C BCDC D8A3 8D88 A2B3 as follows:

    shell
      pub   rsa4096 2024-05-29 [SC]
        8540A6F18833A80E9C1653A42FD21310B49F6B46
  uid                      nginx signing key <[email protected]>

  pub   rsa2048 2011-08-19 [SC] [expires: 2027-05-24]
        573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
  uid                      nginx signing key <[email protected]>

  pub   rsa4096 2024-05-29 [SC]
        9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3
  uid                      nginx signing key <[email protected]>
    Important
    If the fingerprint is different, remove the file.

  4. Add the nginx agent repository:

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

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

    shell
    sudo apt update
sudo apt install nginx-agent

    To install nginx-agent with a specific version (for example, 2.42.0):

    Update your package index and install a specific version of the nginx-agent. Replace <VERSION_CODENAME> with your current Ubuntu codename (for example, jammy, noble).

    shell
    sudo apt update
sudo apt install -y nginx-agent=2.42.0~<VERSION_CODENAME>

  6. Verify the installation:

    sudo nginx-agent -v

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

    nginx-agent -v

  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 restart nginx-agent

  7. Check the Agent log for "Agent Connected"

    sudo cat /var/log/nginx-agent/agent.log | grep "Agent connected"

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
View source
Edit this page
Create a new issue