Skip to content

docs: add agent unprivileged doc #297

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Mar 19, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions content/agent/installation-upgrade/installation-unprivileged.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
---
title: Run without root privileges
weight: 450
toc: true
type: how-to
product: Agent
---

## Overview

If the policies of your organization do not allow running processes as root, you can run NGINX Agent under a user without root privileges.

This also aligns with the principle of least privilege, which is a security concept that limits the access rights of users to the bare minimum permissions they need to perform their work.

---

## Before you begin

Please note that **root access is required to install NGINX Agent**. The agent can be run under a non-root user after the installation.

---

## Installation

The installation process involves installing NGINX Plus without root privileges and then installing NGINX Agent:

### Install NGINX Plus without root privileges

You can install NGINX Plus without root privileges following the steps on the [NGINX Plus installation page]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus/#unpriv_install" >}}). The steps include a script that will allow you to install NGINX Plus in a non-root environment.

{{< note >}}
NGINX Agent has its own user group (`nginx-agent`) which is created when NGINX Agent is installed. The user NGINX is running under is added to this user group during the installation of NGINX Agent. If you change the NGINX user after installing NGINX Agent, you will need to [manually add the new NGINX user]({{< ref "/agent/configuration/configure-nginx-agent-group.md" >}}) to the `nginx-agent` group.
{{< /note >}}

### Install NGINX Agent

After installing NGINX Plus, you can install NGINX agent following the steps on the [NGINX Agent installation page]({{< ref "/agent/installation-upgrade/installation-oss.md" >}}).

### Start NGINX Agent

Run the command corresponding to your operating system to start NGINX Agent:

{{<bootstrap-table "table table-striped table-bordered">}}

| Operating System | Command(s) |
|------------------------------------------------------|------------------------------------------------|
| RHEL, CentOS,<br>Rocky Linux, AlmaLinux,<br>Oracle Linux, Ubuntu,<br>Debian, SLES, Amazon Linux | ```sudo systemctl start nginx-agent``` |
| Alpine Linux | ```sudo rc-service nginx-agent start```<br>or<br>```sudo /etc/init.d/nginx-agent start``` |
| FreeBSD | ```sudo service nginx-agent start``` |

{{</bootstrap-table>}}

You can confirm that NGINX Agent is running under the same user as NGINX Plus by running the following command:

```bash
ps aux | grep nginx-agent
```