End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller API Management Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller API- Management customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Controller Application Delivery Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing NGINX Controller Application Delivery customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

Install NGINX Controller Agent for Non-root Users

How to install the F5 NGINX Controller Agent to run as a non-root user.

This topic describes an early access feature. These features are provided for you to try before they are generally available. You shouldn't use early access features for production purposes.

Overview

This document provides the instructions to run F5 NGINX Controller Agent as a non-root user, by making a few adjustments to the deployment process.

Before You Begin

Before you follow the steps to deploy and run the Controller Agent as a non-root user, install NGINX Controller following the normal installation process. Once you reach the step Install NGINX Controller Agent follow the steps in this guide instead.

Install NGINX Controller Agent to Run as a Non-root User

Take the following steps to add an instance to NGINX Controller:

Open the NGINX Controller user interface and log in.
Select the NGINX Controller menu icon, then select Infrastructure.
On the Infrastructure menu, select Instances > Overview.
On the Instances overview page, select Create.
On the Create Instance page, select Add an existing instance.
Add a name for the instance. If you don’t provide a name, the hostname of the instance is used by default.
To add the instance to an existing Location, select a Location from the list. Or to create a Location, select Create New.

Important:
Once set, the Location for an instance cannot be changed. If you need to change or remove the Location for an instance, you must remove the instance from NGINX Controller, and then add it back.
(Optional) By default, registration of NGINX Plus instances is performed over a secure connection. To use self-signed certificates with the Controller Agent, select Allow insecure server connections to NGINX Controller using TLS. For security purposes, we recommend that you secure the Controller Agent with signed certificates when possible.
Use SSH to connect and log in to the NGINX instance that you want to connect to NGINX Controller.
Copy the curl or wget command that’s shown in the Installation Instructions section on the NGINX instance to download and install the Controller Agent package. When specified, the -i and -l options for the install.sh script refer to the instance name and Location, respectively. You need to modify this command to use a non-root user
Add the parameter CONTROLLER_USER='<non-root user of your choice>' to the curl or wget command, substituting the value in the brackets with your desired non-root user.
(Optional) Add the parameter CONTROLLER_GROUP='<group choice>' to the curl or wget command, substituting the value in the brackets with your desired group. If this parameter is not set, a new group with the same name as the user will be created.
The curl or wget command looks similar to this example after applying the required changes:
```
curl -sS -L https://<controller FQDN>/install/controller-agent > install.sh && API_KEY='<API KEY>' CONTROLLER_USER='<non-root user>' CONTROLLER_GROUP='<optional group>' -i <instance name> -l <instance location>
```
Note:

Make sure you enter the commands to download and run the install.sh script on the NGINX Plus system, and not on the NGINX Controller.

NGINX Controller 3.6 and earlier require Python 2.6 or 2.7. You’ll be prompted to install Python if it’s not installed already. Python is not required for NGINX Controller v3.7 and later.

If CONTROLLER_USER is not set, during the installation you will see the message Installing agent to run as root in red.

Running agent as non-root changes the nap-syslog port to 5114 in both containerized and non-containerized instances.

After a few minutes, the NGINX instance will appear on the Instances overview page.

For the NGINX Agent to run properly, NGINX Plus must be running as the same user and group as the Agent. To change the user and group NGINX Plus is running as after installing the agent:

Manually edit the /lib/systemd/system/nginx.service file and under the [Service] block add the lines User=<non-root-user> and Group=<optional group> replacing the values in brackets with the values chosen during the installation.
Run sudo chown -R <non-root-user>:<optional group> /etc/nginx/ /var/log/nginx/ /var/cache/nginx/ to change the permissions to your non-root user.
Ensure the ports NGINX is listening to are all above 1000: Check the NGINX default.conf file (usually /etc/nginx/conf.d/default.conf) and make sure that the listen values are all over 1000.
(CentOS/RHEL) If you’re installing the Controller Agent as a non-root user on CentOS or RHEL, make these additional changes:
- In in the [Service] section of /lib/systemd/system/nginx.service, set the location for the PIDfile to:
```
[Service]
PIDFile=/var/tmp/nginx.pid
```
- In /etc/nginx/nginx.conf, set the pid directive to:
```
pid        /var/tmp/nginx.pid;
```
Run sudo systemctl daemon-reload && sudo systemctl restart nginx to pick up the new configuration.

Verification Steps

Run top -u <non-root-user> for your chosen user. The /usr/bin/nginx-controller-agent process will appear in the list of processes.