Installation Parameters

Parameter Description

info

Note: When performing an overwrite installation, if no parameters are specified, the previous installation configuration will be used by default.
Installation parameter formats:

• Windows: installer.exe {parameter list}
• Linux/AIX: sh installer.sh --target {installation directory} config {parameter list}

installer.exe and installer.sh should be replaced with the actual installer names. For details, see: Installation.

In examples, "..." represents other installation parameters.

Parameter	Required	Supported Platforms	Description	Example
--target [val]① [1.2.2+]	No	linux	Absolute installation directory path: Root user: default /opt Non-root user: default $HOME	sh installer.sh --target /path config ... Note: Ensure all directory levels have permissions ≥ 755. Check with: dir="/opt"; while [ "$dir" != "/" ]; do [ $(stat -c %a "$dir") -lt 755 ] && echo "$dir insufficient"; dir=$(dirname "$dir"); done
-a, --account [val]	Yes	linux windows aix	Account GUID	sh installer.sh config -a "xxxx-xxx" ...
-u, --url [val]	See ③	linux windows aix	APM Controller URL	sh installer.sh config -u "https://oneupload.bonree.com/APM" ...
-l, --logs-url [val] [7.2.0+]	See ③	linux	Logs Controller URL	sh installer.sh config -l "https://oneupload.bonree.com/controller/logs" ...
--set-network-zone [val] [6.6.0+]	No	linux windows	Set network zone Default: not set on first installation If SmartGate is installed directly on the host and has this parameter configured, it will inherit SmartGate's NetworkZone.	sh installer.sh config --set-network-zone "default" ...
--set-cluster-name [val] [6.9.0+]	No	linux windows	Set cluster name Default: not set on first installation If SmartGate is installed directly on the host and has this parameter configured, it will inherit SmartGate's ClusterName.	sh installer.sh config --set-cluster-name "default" ...
--set-env-id [val] [7.4.0+]	No	linux windows	Set environment ID Default: not set on first installation If SmartGate is installed directly on the host and has this parameter configured, it will inherit SmartGate's EnvId.	sh installer.sh config --set-env-id "default" ...
--set-host-attr "datacenter=[val]"⑦ [9.1.0+]	No	linux windows	Set host attributes (e.g., datacenter) Default: not set If SmartGate is installed directly on the host and has this parameter configured, it will inherit SmartGate's host-attr.	sh installer.sh config --set-host-attr "datacenter=123" ...
--set-host-tag [k1=v1,k2]⑦ [9.1.0+]	No	linux windows	Set host tags Default: not set If SmartGate is installed directly on the host and has this parameter configured, it will inherit SmartGate's host-tag.	sh installer.sh config --set-host-tag "tag=123,tag2" ...
--disable-dumpproc [true/false]② [6.10.0+]	No	linux⑥	Disable crash/event collection Default: false	sh installer.sh config --disable-dumpproc true ...
-t, --enable-agent-types [val]	No	linux windows aix	List of agents to enable, comma-separated Default: "java,dotnet,php,go"	sh installer.sh config -t "java,dotnet,php,go,nginx,apache" ...
--user [val] --group [val] --non-root-mode [true/false]② [2.1.0+]	No	linux④	Default: SmartAgent service runs as bruser. User/Group creation: if user/group does not exist, they are automatically created with: - No password - Login disabled (only for running SmartAgent) The primary group of an existing user cannot be changed, and the username must be verified to be in the correct group.	See: Non-privileged Mode
--force [7.2.0+]	No	linux	Non-root installation	Force installation (required for non-root or container installation; no effect for root). See: Non-root Installation on Host
--reset-conf ... --set-conf ... --delete-conf ... [>=5.8.0 or <6.0.0, 6.7.0+]	No	linux	Modify configuration files	See: Modify Configuration at Installation
--set-inject-mode [0/1]⑤ [8.3.1+]	No	linux	Set injection mode: 0 - Inject into all containers by default (then match deep process rules) 1 - Do not monitor all containers by default	sh installer.sh config --set-inject-mode 0 ...
--set-monitoring-mode [infra|full] [9.7.0+]	No	linux	Set monitoring mode Default: full infra: infrastructure-only (no automatic language agent injection, no eBPF agent) full: full-stack monitoring	sh installer.sh config --set-monitoring-mode infra ...

info

① [val] indicates a placeholder value
② [true/false]: can only be true or false
③ At least one of APM Controller (-u) or Logs Controller (-l) must be specified if any other parameters are present.
- Missing -u disables APM functionality.
- Missing -l disables log collection.
④ Parameter not supported in non-root installation; will be ignored if set.
⑤ [0/1]: can only be 0 or 1
⑥ Containerized deployment always true (host root directory may not reflect the real system root, so forcibly disabled).
⑦ [k1=v1,k2]: comma-separated key-value pairs, values can be empty (e.g., "k1=v1,k2=,k3")

---

Non-privileged Mode

warning

Non-root installation is not supported
Linux only

In this mode, SmartAgent runs its service processes as a non-privileged user and leverages Linux Filesystem Capabilities to restrict the process to the minimal required privileges.

---

System Requirements

• libcap2 must be installed (check for libcap.so.2). For example, RHEL 5 does not include libcap2 by default.
• Extended attributes must be supported: xattr(7)
• The installation disk cannot be mounted with noexec or nosuid.
• Linux Filesystem Capabilities must be supported and enabled (Kernel ≥ 2.6.26, e.g., SLES 11 has this feature disabled by default).

---

Enabling Linux Filesystem Capabilities

SLES 11 does not enable Linux Filesystem Capabilities by default. Other Linux distributions may also disable it. During installation, SmartAgent will warn and continue in privileged mode:

WARNNING: Failed to enable non-privileged mode, kernel `does not` support file capabilities.

Please check your kernel boot parameters to see if Linux Filesystem Capabilities is enabled. You can verify using the following command:

$ cat /proc/cmdline

If the output contains file_caps=1, the feature is enabled.

To enable it, add file_caps=1 to the kernel boot parameters. For example, on SUSE Linux Enterprise Server 11, you can use YaST to edit the kernel boot parameters and then restart the machine.

---

Installation Options

# --non-root-mode [true/false]  Enable/disable non-privileged mode. Default is `true` on first installation.
# --user [user name]            The user to run SmartAgent processes in non-root mode. Default is `bruser`.
# --group [group name]          The group for SmartAgent files. Defaults to the value of `--user` and must be used together with `--user`.

# Examples:
# Run bonree-agent service as root
sudo bash installer.sh config --non-root-mode false
# Run bonree-agent service as myuser:myuser
sudo bash installer.sh config --user myuser --non-root-mode true

---

Modifying Configuration During Installation

warning

Linux only

Parameter	Description (supports yaml, json, ini)
--reset-conf {file} {value}	Overwrite the specified configuration item
--set-conf {file} {value}	Set or append the specified configuration item
--delete-conf {file} {value}	Delete the specified configuration item

Sub-parameter	Description
file	The file to modify. If relative, the actual path is install_dir/conf/{file}
value	The content to modify or delete

example

# Modify Java agent agent configuration:
sudo bash installer.sh config --reset-conf java/bonree.yml "common.brdbglogLevel: finest"

# Enable Java agent debug. Use backslash to escape dots in keys
sudo bash installer.sh config --set-conf java/bonree.yml "common.bonree\.debug: true"

# Append Node.js agent array-type configuration
sudo bash installer.sh config --set-conf nodejs/bonree.yml "blacklist: [_next, _nuxt]"

# Overwrite agentloader.yml array-type configuration
sudo bash installer.sh config --reset-conf agentloader.yml \
  "jvm.option.javaagent.ignoreList: [xxx.jar, yyy.jar]"

# Append agentloader.yml array-type configuration
sudo bash installer.sh config --set-conf agentloader.yml \
  "jvm.option.javaagent.ignoreList: [xxx.jar, yyy.jar]"

# Parameters can be used repeatedly to modify multiple configuration items.
# Delete a Java configuration and modify a PHP configuration in one command
sudo bash installer.sh config \
  --delete-conf java/bonree.yml "common.brdbglogLevel" \
  --reset-conf php/brapm.ini "brapm.log_conf_file_size = 50"