Skip to main content
Version: 3.7.0

Install SmartAgent on Linux as a Non-root User

Overview​

This document describes how to install SmartAgent on a Linux system as a non-root user.

Key characteristics of this installation method:

  • No root privileges required
  • Only monitors applications started by the current user
  • Limited functionality, suitable for restricted environments or quick trials
info

If you have root privileges, it is recommended to use the Linux (root) Installation for full functionality.

Prerequisites​

Before installation, make sure the following conditions are met:

Limitations​

Supported since version 7.2.0:

  • Supported on Linux (x86, x64, aarch64) only

  • Does not support multiple non-root agents on the same host

  • Cannot coexist with a root-installed SmartAgent

  • Does not support monitoring containerized applications

  • Does not support collecting container-related metrics

  • Does not support auto-start on boot

  • Does not support monitoring applications with privilege bits (setuid / any capabilities)

    Example:

    # nginx with setuid enabled
    ls -l $(which nginx)
    -rwsr-sr-x 1 root root 1338032 Jun 28  2023 /usr/sbin/nginx

    # application with capabilities
    getcap $(which nginx)
    /usr/sbin/nginx = cap_net_bind_service+eip

Installation & Upgrade​

  1. Log in to the Bonree ONE platform, go to Configuration > Agent Installation, and select Host Mode as the deployment mode.

  2. Download the latest SmartAgent-Linux installation package for your CPU architecture:

    wget -O Bonree-SmartAgent-Linux-<version>.sh \
    'https://one.bonree.com/agent/down/Bonree-SmartAgent-Linux-<version>.sh' \
    --header='Authorization:<token>'

  3. Run the installation command with the necessary parameters (detailed installation parameters):

    info

    Non-root installation requires the --force parameter.

    /bin/sh Bonree-SmartAgent-Linux-<version>.sh config \
      -a "<accountGUID>" \
      -u "https://oneupload.bonree.com/APM" \
      -t "java,php,go,dotnet" \
      --set-env-id "default" \
      --force

  • Re-login to the shell or run the following command to configure the current session and auto-inject required environment variables:

    source $HOME/.smartagent/conf/setup.sh

  • Example: restart the application to be monitored.

    warning

    After first installation, if the target application is managed by another process manager, you must restart that manager.
    It is recommended to check if environment variables are active after restarting the shell session.

    nohup java -jar demo.jar &

Uninstallation​

bash $HOME/bonree/apm/scripts/uninstall.sh
warning

After uninstallation, do not immediately delete the agent directory until all monitored applications or containers have been restarted, otherwise business issues may occur.

Service Management (executed by install user)​

# Check status
$HOME/bonree/apm/scripts/bonree-agent.sh status

# Stop the agent
$HOME/bonree/apm/scripts/bonree-agent.sh stop

# Restart the agent
$HOME/bonree/apm/scripts/bonree-agent.sh restart

About Auto-injection​

Environment Configuration​

  • During installation, $HOME/.bashrc or $HOME/.bash_profile will be modified
  • If .bashrc or .bash_profile exists, the following line will be appended: 
    source $HOME/.smartagent/conf/setup.sh 2>/dev/null
  • Other files may be modified depending on system and user configuration

Check if Auto-injection Works​

env | grep LD_PRELOAD

If the output contains LD_PRELOAD with the correct path, it is effective.

If not, add the following line at the beginning of your application startup script:

source $HOME/.smartagent/conf/setup.sh
example
[username@myhost ~]$ env | grep LD_PRELOAD
LD_PRELOAD=/home/lll/bonree/apm/$LIB/libagentloader.so

Limitations​

  • By default, only monitors applications started by the current user

Cross-user Support​

  1. Create a dedicated agent user (e.g., bonreeapm) and set /home/bonreeapm permissions to 755
  2. Install the agent under that user
  3. Add the following line to other monitored users’ .bashrc or .bash_profile:
source /home/bonreeapm/.smartagent/conf/setup.sh 2>/dev/null
  1. Re-login and restart applications to be monitored