Linux agent running modes

The Infrastructure agent for Linux environments can run as root, privileged, or unprivileged user, which are described below:

Mode Overview
Root

Installed by default. Runs as root and has total access to all the system metrics and inventory.

Privileged

Runs as a non-privileged user named nri-agent that is created automatically during the installation process.

Normal users do not have READ access to all the system metrics, so the agent will not be able to report all the metrics of the root mode. However, privileged mode can collect more metrics than unprivileged mode, including most of the inventory. This is because at installation time, the /usr/bin/newrelic-infra executable is granted with CAP_SYS_PTRACE and CAP_DAC_READ_SEARCH kernel capabilities.

Unprivileged

Runs as a non-privileged user named nri-agent that is created automatically during the installation process.

This mode is the most restricted. Normal users do not have READ access to all the system metrics, so the agent will not be able to report all the metrics of the root or privileged modes.

Metrics and inventory provided

The agent provides different metrics and inventory depending on the running mode:

Mode Metrics and inventory
Root All of the documented data and instrumentation values.
Privileged

All of the values from root mode, except:

  • SELinux inventory: This depends on the semodule command, which requires root access.
  • Docker process metrics: These are not enabled by default. However, you can manually enable them by giving access rights to the nri-agent user.
Unprivileged

All of the values from privileged mode, except:

Process samples do not report these metrics:

  • File descriptor count
  • I/O read bytes per second
  • I/O read count per second
  • I/O total read bytes
  • I/O total read count
  • I/O total write bytes
  • I/O total write count
  • I/O write bytes per second
  • I/O write count per second

The following inventory sources are not reported:

  • config/sshd
  • kernel/sysctl
  • packages/rpm
  • packages/dpkg
  • services/pidfile on SysV-based distributions

Run integrations

As root, integrations will run as usual. When running as privileged or unprivileged user, integrations will execute properly, although some custom integrations (for example, built by customers or technical sales staff) that depend on access to root may need additional configuration.

On-host integrations

In general, on-host integrations will run with the non-root agent as long as the nri-agent has permissions on the integration cache files.

The default path where the integration cache files are stored is /tmp. To change the path, set the environment variable NRIA_CACHE_PATH. In this situation, use the following instructions to target the provided cache path folder instead of /tmp.

On-host integrations Cache path folder
Apache
sudo chown nri-agent:nri-agent -R /tmp/nr-apache.json
Cassandra
sudo chown nri-agent:nri-agent -R /tmp/nr-integrations
MySQL
sudo chown nri-agent:nri-agent -R /tmp/nr-mysql.json
Nginx
sudo chown nri-agent:nri-agent -R /tmp/nr-nginx.json
Redis
sudo chown nri-agent:nri-agent -R /tmp/nr-redis.json
Custom integrations

If your custom integration doesn't require root privileges, then it’s compatible with the rootless mode. To run it, you just need to change the owner:group of the cache file as explained above.

If your integration requires to be executed with a privileged user, you can use the integration_user argument in the configuration integration.

Set the running mode for your agent

When deciding which run mode to use, consider how much data you want to be able to collect and analyze, or how much data you want to restrict.

For default and assisted installations, you can set the running mode by including the NRIA_MODE environment variable set to either ROOT, PRIVILEGED, or UNPRIVILEGED.

For manual installations, follow the instructions described in our docs.

Switch running modes

From root to privileged/unprivileged

To switch the running mode from root to privileged or unprivileged, follow the installation/update instructions in this doc.

From privileged/unprivileged to any other mode

To change the running mode from privileged or unprivileged to any other mode:

  1. Follow these steps:

    Debian/Ubuntu

    dpkg --purge newrelic-infra

    OR

    sudo apt-get remove --purge newrelic-infra
    Centos/Suse/RedHat/Amazon
    rpm -e newrelic-infra

    OR

    sudo yum remove newrelic-infra

    OR

    sudo zypper rm newrelic-infra
  2. After making sure the agent is completely removed, reinstall the agent with the selected mode.

Update the agent

Follow standard procedures to update the Infrastructure agent.

For more help

Recommendations for learning more: