Install NGINX Controller Agent for Non-root Users
How to install the NGINX Controller Agent to run as a non-root user.
This topic documents a beta feature. Beta features are provided for you to try out before they are released. You shouldn't use beta features for production purposes.
This document provides the instructions to run NGINX Controller Agent as a non-root user, by making a few adjustments to the deployment process.
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.
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.
wgetcommand that’s shown in the Installation Instructions section on the NGINX instance to download and install the Controller Agent package. When specified, the
-loptions for the
install.shscript 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
wgetcommand, substituting the value in the brackets with your desired non-root user.
(Optional) Add the parameter
CONTROLLER_GROUP='<group choice>'to the
wgetcommand, 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.
wgetcommand 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.shscript 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.
CONTROLLER_USERis not set, during the installation you will see the message
Installing agent to run as rootin red.
Running agent as non-root changes the nap-syslog port to
5114in 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.servicefile and under the
[Service]block add the lines
Group=<optional group>replacing the values in brackets with the values chosen during the installation.
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
/etc/nginx/conf.d/default.conf) and make sure that the
listenvalues are all over
(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
/lib/systemd/system/nginx.service, set the location for the
/etc/nginx/nginx.conf, set the
sudo systemctl daemon-reload && sudo systemctl restart nginxto pick up the new configuration.
top -u <non-root-user> for your chosen user. The
/usr/bin/nginx-controller-agent process will appear in the list of processes.
This documentation applies to the following versions of NGINX Controller: 3.0, 3.1, 3.2, 3.3, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 3.10, 3.12, 3.13, 3.14, 3.15, 3.16.1, 3.17, 3.18, 3.18.1, 3.18.2 and 3.18.3.
This documentation applies to the following versions of NGINX Controller API Management module: 3.18, 3.18.1, 3.19, 3.19.1, 3.19.2, 3.19.3 and 3.19.4.
This documentation applies to the following versions of NGINX Controller App Delivery module: 3.20, 3.20.1, 3.21, 3.22, 3.22.1, 3.22.2, 3.22.3, 3.22.4 and 3.22.5.