# Install from NGINX Plus repo

Type of document: How-to guide
Product: NGINX Agent

---


**Note:** 
If you are using [NGINX One Console](/nginx-one-console/getting-started.md)
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](/nginx-one-console/connect-instances/add-instance.md)

## Overview

Follow the steps in this guide to install F5 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](/nginx-one-console/agent/overview/tech-specs.md#supported-distributions)
- 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 Alpine Linux

#### Expand instructions

1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download
   your `nginx-repo.crt` and `nginx-repo.key` files.

1. Copy the files to the `/etc/apk/` directory:

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

1. Install the prerequisites:

   ```shell
   sudo apk add openssl curl ca-certificates
   ```

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

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

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

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

1. Verify that downloaded file contains the proper key:

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

   The output should contain the following modulus:

   ```none
   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)
   ```

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

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

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

   ```shell
   sudo apk add nginx-agent
   ```

1. Verify the installation:

   ```shell
   sudo nginx-agent -v
   ```

### Install NGINX Agent on Amazon Linux

#### Expand instructions

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

   ```shell
   sudo mkdir -p /etc/ssl/nginx
   ```

1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download
   your `nginx-repo.crt` and `nginx-repo.key` files.

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

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

1. Install the prerequisites:

   ```shell
   sudo yum install yum-utils procps ca-certificates
   ```

1. 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=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
   ```

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

   ```shell
   sudo yum install nginx-agent
   ```

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

   ```shell
   sudo yum install -y nginx-agent-2.42.0
   ```
   

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

1. Verify the installation:

   ```shell
   sudo nginx-agent -v
   ```

### Install NGINX Agent on Debian

#### Expand instructions

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

   ```shell
   sudo mkdir -p /etc/ssl/nginx
   ```

1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download
   your `nginx-repo.crt` and `nginx-repo.key` files.

1. Copy the files to the `/etc/ssl/nginx/` directory:

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

1. Install the prerequisites:

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

1. Add the `nginx-agent` repository:

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

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

   ```conf
   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";
   ```

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

   ```shell
   sudo apt update
   sudo apt install nginx-agent
   ```

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

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

1. Verify the installation:

   ```shell
   sudo nginx-agent -v
   ```

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

#### Expand instructions

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

   ```shell
   sudo mkdir -p /etc/ssl/nginx
   ```

1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download
   your `nginx-repo.crt` and `nginx-repo.key` files.

1. Copy the files to the `/etc/ssl/nginx/` directory:

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

1. Install the prerequisites:

   ```shell
   sudo yum install yum-utils procps
   ```

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

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

1. Add the following lines to `nginx-agent.repo`:

   ```ini
   [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
   ```

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

   ```shell
   sudo yum install nginx-agent
   ```

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

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

1. Verify the installation:

   ```shell
   sudo nginx-agent -v
   ```

### Install NGINX Agent on SLES

#### Expand instructions

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

   ```shell
   sudo mkdir -p /etc/ssl/nginx
   ```

1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download
   your `nginx-repo.crt` and `nginx-repo.key` files.

1. Copy the files to the `/etc/ssl/nginx/` directory:

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

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

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

1. Install the prerequisites:

   ```shell
   sudo zypper install curl ca-certificates gpg2 gawk
   ```

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

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

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

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

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

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

1. 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 <signing-key-2@nginx.com>

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

   pub   rsa4096 2024-05-29 [SC]
         9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3
   uid                      nginx signing key <signing-key-3@nginx.com>
   ```

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

   ```shell
   sudo rpmkeys --import /tmp/nginx_signing.key
   ```

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

   ```shell
   sudo zypper install nginx-agent
   ```

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

   ```shell
   sudo zypper install -y nginx-agent=2.42.0
   ```
   

1. Verify the installation:

   ```shell
   sudo nginx-agent -v
   ```

### Install NGINX Agent on Ubuntu

#### Expand instructions

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

   ```shell
   sudo mkdir -p /etc/ssl/nginx
   ```

1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5/) and download your `nginx-repo.crt` and `nginx-repo.key` files.

1. Copy the files to the `/etc/ssl/nginx/` directory:

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

1. Install the prerequisites:

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

1. Download and add [NGINX signing key](https://cs.nginx.com/static/keys/nginx_signing.key):

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

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

    ```conf
    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";
    ```

1. Add the `nginx-agent` repository:

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

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

   ```shell
   sudo apt update
   sudo apt install nginx-agent
   ```

   **Note:** 
   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>
   ```
   

1. Verify the installation:

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

   ```shell
   nginx-agent -v
   ```

1. Locate the NGINX Agent Configuration File:

   ```shell
   /etc/nginx-agent/nginx-agent.conf
   ```

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

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

1. Uncomment the command block, and set the token to your data plane key
1. Save the changes and close the editor
1. Restart the NGINX Agent service:

   ```shell
   sudo systemctl restart nginx-agent
   ```

1. Check the Agent log for `"Agent Connected"`

   ```shell
   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:

```shell
sudo systemctl start nginx-agent
```

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

```shell
sudo systemctl enable nginx-agent
```

To stop NGINX Agent, run the following command:

```shell
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:

```shell
sudo systemctl status nginx-agent
```

To check the version installed, run the following command:
```shell
sudo nginx-agent -v
```