Linux Install Using the RPM Package

1. Before installing, review Install the Machine Agent.
2. Download and install the RPM Package. With administrative privileges, enter the following CLI code where <pkg-name.rpm> is the name of the package for your environment, such as appdynamics-machine-agent-<version>.x86_64.rpm.
   CODECopy

   sudo rpm -ivh <pkg-name.rpm>

   sudo rpm -ivh <pkg-name.rpm>

   The agent files are installed in opt/appdynamics/machine-agent and the agent is added as a service.

3. Gather your configuration details and configure the agent by editing the <machine_agent_home>/conf/controller-info.xml file or by adding system properties to the JVM startup script file. See Linux Install Using the RPM Package.
   1. (Required) Configure the Controller host name, port number, and account access key.
   2. (Optional) Review memory requirements. See Machine Agent Requirements and Supported Environments.
   3. (Optional) Configure the agent to use SSL. See Enable SSL for Machine Agent.
   4. (Optional) Configure the agent to use proxy settings. See Machine Agent Configuration Properties.
   5. (Required for Multi-Tenant Mode or SaaS installations) Configure the Agent Account Information. See Multi-Tenant Controller Accounts.
   6. (Optional) Determine if you need to specify an application name and tier name. See Machine Agent Installation Scenarios. If you are installing the Machine Agent on the same server with any Splunk AppDynamics app agent, do not specify application name and tier name.
4. Start the Agent. You can start the agent as a service (requires sudo or root user) or from the command line. If systemd was detected during installation, you can use the systemctl command to start the agent service.
   • Using SysV: service appdynamics-machine-agent start
   • Using systemd: systemctl start appdynamics-machine-agent
   • From the Command Line: <machine_agent_home>/bin/machine-agent
   • From the Launcher: <machine_agent_home>/etc/init.d/appdynamics-machine-agent start

Install and manage the Machine Agent and the bundled OpenTelemetry Collector on Linux systems that use RPM and systemd.

1. Configure the Machine Agent and collector independently.

   For the Machine Agent, edit <machine_agent_home>/conf/controller-info.xml or its RPM-installed link at /etc/appdynamics/machine-agent/controller-info.xml.

   For the OTel Collector, edit /etc/appdynamics/machine-agent/otel/agent_config.yaml and set its environment in /etc/sysconfig/splunk-otel-collector.

   The packaged links are:

   • /etc/appdynamics/machine-agent/otel/agent_config.yaml → /opt/appdynamics/machine-agent/conf/otel/agent_config.yaml

   • /etc/sysconfig/splunk-otel-collector → /opt/appdynamics/machine-agent/etc/sysconfig/splunk-otel-collector

   • /opt/appdynamics/machine-agent/etc/systemd/system/splunk-otel-collector.service → /etc/systemd/system/splunk-otel-collector.service

   Before starting the collector with the bundled default exporter configuration, set the required Splunk Observability Cloud credentials:

   SHELLCopy

   SPLUNK_ACCESS_TOKEN=<access-token> SPLUNK_REALM=<realm>

   SPLUNK_ACCESS_TOKEN=<access-token>
   SPLUNK_REALM=<realm>

   A custom exporter configuration can have different requirements. See Combined Agent for Infrastructure Visibility for configuration details.

   For RPM installations that use systemd, the collector does not read the account name from Machine Agent controller-info.xml. To add AppDynamics account resource context, also set:

   SHELLCopy

   APPDYNAMICS_AGENT_ACCOUNT_NAME=<account-name>

   APPDYNAMICS_AGENT_ACCOUNT_NAME=<account-name>

   APPDYNAMICS_AGENT_ACCOUNT_NAME supplies resource context; it is not a credential required to start the collector. The bundled configuration sets deployment.environment.name and appd.account.name from this value. Setting DEPLOYMENT_ENVIRONMENT does not change deployment.environment.name in the bundled configuration.

2. Manage the collector service.

   Start the collector for the current boot:

   SHELLCopy

   sudo systemctl start splunk-otel-collector

   sudo systemctl start splunk-otel-collector

   Enable the collector at boot and start it immediately:

   SHELLCopy

   sudo systemctl enable --now splunk-otel-collector

   sudo systemctl enable --now splunk-otel-collector

   Check its status:

   SHELLCopy

   sudo systemctl status splunk-otel-collector

   sudo systemctl status splunk-otel-collector

   Stop the collector and disable boot-time startup:

   SHELLCopy

   sudo systemctl disable --now splunk-otel-collector

   sudo systemctl disable --now splunk-otel-collector

   Restart an already-running collector after an approved configuration change:

   SHELLCopy

   sudo systemctl restart splunk-otel-collector

   sudo systemctl restart splunk-otel-collector

3. Select a deployment mode on systemd.

   For Machine Agent mode:

   SHELLCopy

   sudo systemctl enable --now appdynamics-machine-agent sudo systemctl disable --now splunk-otel-collector

   sudo systemctl enable --now appdynamics-machine-agent
   sudo systemctl disable --now splunk-otel-collector

   For Dual signal mode:

   SHELLCopy

   sudo systemctl enable --now appdynamics-machine-agent sudo systemctl enable --now splunk-otel-collector

   sudo systemctl enable --now appdynamics-machine-agent
   sudo systemctl enable --now splunk-otel-collector

   For OTel only mode:

   SHELLCopy

   sudo systemctl disable --now appdynamics-machine-agent sudo systemctl enable --now splunk-otel-collector

   sudo systemctl disable --now appdynamics-machine-agent
   sudo systemctl enable --now splunk-otel-collector

   enable --now starts a service and enables it at boot. disable --now stops a service and disables boot-time startup.

   Verify the service state:

   SHELLCopy

   systemctl is-enabled appdynamics-machine-agent splunk-otel-collector systemctl is-active appdynamics-machine-agent splunk-otel-collector

   systemctl is-enabled appdynamics-machine-agent splunk-otel-collector
   systemctl is-active appdynamics-machine-agent splunk-otel-collector

   Note:

   For RPM installations that use systemd, SPLUNK_OTEL_ENABLED=true, -Dsplunk.otel.enabled=true, <otel-enabled>true</otel-enabled>, SPLUNK_OTEL_ONLY=true, and -Dsplunk.otel.only=true do not enable or start the independent collector service. Manage both services explicitly with systemctl.

4. Configure Docker process selection and PID-level metrics.

   Machine Agent makes Docker PID-level metrics opt in and starts enforcing the Docker individual-process selector in both the Docker API and cgroup collection paths.

   Control	Environment variable	JVM system property	DockerMonitoring.yml setting	Default
   Docker PID-level metrics	APPDYNAMICS_DOCKER_PROCESS_METRICS_ENABLED	appdynamics.docker.process.metrics.enabled	processMonitorConfig.processLevelMetricsEnabled	false
   Docker individual-process selector	APPDYNAMICS_DOCKER_PROCESS_SELECTOR_REGEX	appdynamics.docker.process.selector.regex	processMonitorConfig.processSelectorRegex	Packaged selector

   For each setting, precedence is environment variable, JVM system property, YAML setting, and then the default. Changes to DockerMonitoring.yml normally reload without a Machine Agent restart. Environment-variable and JVM-property changes require a restart.

   • containerMonitoringConfig.containerProcessSelectorRegex chooses which containers are monitored. Its Java regular expression must match an entire process command line; a container is selected when any process matches.

   • processMonitorConfig.processSelectorRegex chooses which individual processes inside a selected container contribute process metrics and metadata. It searches each full command line unless the expression is anchored with ^ and $.

   The packaged Docker selector excludes kernel-style command lines and direct executions whose executable is exactly sleep, curl, or sh, including path-qualified forms. Wrapper commands and similar executable names remain eligible.

   When process monitoring remains enabled, setting Docker PID-level metrics to false suppresses only PID-specific metric series. Process-class metrics and process metadata continue for eligible processes. A process excluded by the individual-process selector contributes no process-class metrics, PID-level metrics, or process metadata.

   To enable Docker PID-level metrics:

   YAMLCopy

   processMonitorConfig: processLevelMetricsEnabled: true

   processMonitorConfig:
     processLevelMetricsEnabled: true

   Or use an environment variable and restart the Machine Agent:

   SHELLCopy

   export APPDYNAMICS_DOCKER_PROCESS_METRICS_ENABLED=true

   export APPDYNAMICS_DOCKER_PROCESS_METRICS_ENABLED=true

5. Handle an empty application name.
   Note:

   Starting with Machine Agent 26.8.0, an empty or whitespace-only <application-name> value is treated as unspecified. The Machine Agent does not send a blank application name during registration.

6. Configure host process-level metrics.

   The precedence for the host PID-level property is:

   1. APPDYNAMICS_MACHINE_AGENT_PROCESS_METRICS_ENABLED

   2. appdynamics.machine.agent.process.metrics.enabled

   3. <process-metrics-enabled> in controller-info.xml

   4. Default value false

   <process-metrics-enabled> is supported but is not present in the shipped templates. When XML configuration is used, add it under <controller-info> and restart the Machine Agent. Environment-variable and JVM-property changes also require a restart.

   Setting host PID-level metrics to false suppresses only PID-specific metric series. Process-class metrics and process metadata continue for eligible processes when process monitoring and Server Visibility remain enabled.

7. Configure remediation log-path validation.

   Starting with Machine Agent 26.8.0, you can restrict the log paths that a remediation action can collect from a monitored host. The allowlist is configured locally on every target Machine Agent; the Controller does not distribute or synchronize it.

   Important:

   Validation is disabled by default for backward compatibility. While validation is disabled, action-configured log paths retain the previous unrestricted behavior and the allowlist has no effect. To restrict collection, explicitly enable validation, configure every required allowed root, and restart the Machine Agent.

   When validation is enabled:

   • No directory is allowed automatically, including the Machine Agent logs directory.

   • A requested path is collected only when it equals or is beneath an explicitly configured directory root.

   • If the allowlist is empty or contains no valid roots, all action-configured log paths are rejected.

   • Multiple requested paths are evaluated independently. An allowed path can still be collected when another path is rejected.

   • A rejected path is not compressed or uploaded. Its rejection does not fail an otherwise successful remediation action.

   • Machine Agent-generated remediation script output continues to be captured.

   The Machine Agent resolves requested paths and allowed roots to absolute real or canonical paths and uses path-aware containment. This rejects directory traversal, sibling-prefix matches, and symbolic-link escapes outside an allowed root.

8. Configure remediation settings.

   Purpose	controller-info.xml element	JVM system property	Environment variable	Type	Default	Required
   Enable validation	remediation-log-path-validation-enabled	appdynamics.machine.agent.remediation.logPathValidation.enabled	APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_VALIDATION_ENABLED	Boolean	false	No
   Allowed directory roots	remediation-log-path-allowlist	appdynamics.machine.agent.remediation.logPath.allowlist	APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_ALLOWLIST	Comma-separated string	Empty	No; at least one valid root is operationally necessary when validation is enabled

   Configuration precedence is environment variable, JVM system property, and then controller-info.xml. Configure existing, accessible absolute directory roots. Use the narrowest roots required by your remediation actions.

   TEXTCopy

   /opt/app/logs,/var/log/myapp

   /opt/app/logs,/var/log/myapp

   On Windows:

   TEXTCopy

   C:\App\logs,D:\Service\logs

   C:\App\logs,D:\Service\logs

   Configure the XML elements:

   XMLCopy

   <remediation-log-path-validation-enabled>true</remediation-log-path-validation-enabled> <remediation-log-path-allowlist>/opt/app/logs,/var/log/myapp</remediation-log-path-allowlist>

   <remediation-log-path-validation-enabled>true</remediation-log-path-validation-enabled>
   <remediation-log-path-allowlist>/opt/app/logs,/var/log/myapp</remediation-log-path-allowlist>

   Or supply JVM properties:

   SHELLCopy

   -Dappdynamics.machine.agent.remediation.logPathValidation.enabled=true -Dappdynamics.machine.agent.remediation.logPath.allowlist=/opt/app/logs,/var/log/myapp

   -Dappdynamics.machine.agent.remediation.logPathValidation.enabled=true
   -Dappdynamics.machine.agent.remediation.logPath.allowlist=/opt/app/logs,/var/log/myapp

   Or configure environment variables:

   SHELLCopy

   export APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_VALIDATION_ENABLED=true export APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_ALLOWLIST=/opt/app/logs,/var/log/myapp

   export APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_VALIDATION_ENABLED=true
   export APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_ALLOWLIST=/opt/app/logs,/var/log/myapp

   For PowerShell on Windows:

   POWERSHELLCopy

   $env:APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_VALIDATION_ENABLED = "true" $env:APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_ALLOWLIST = "C:\App\logs,D:\Service\logs"

   $env:APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_VALIDATION_ENABLED = "true"
   $env:APPDYNAMICS_MACHINE_AGENT_REMEDIATION_LOG_PATH_ALLOWLIST = "C:\App\logs,D:\Service\logs"

   Restart the Machine Agent after changing either setting.

9. Enable remediation log-path restrictions safely after an upgrade.

   1. Identify every directory root used by existing remediation actions.

   2. Configure the narrowest required roots in the allowlist.

   3. Enable validation.

   4. Restart the Machine Agent.

   5. Run a remediation action and review the Machine Agent log for rejected paths or invalid allowlist entries.

   Enabling validation without a valid allowlist intentionally rejects every action-configured log path. Setting the allowlist without enabling validation does not restrict collection.

10. Troubleshoot rejected paths.

    When validation rejects a path, the Machine Agent writes a warning containing the submitted path and rejection reason without logging file contents. The default log location is <machine_agent_home>/logs/machine-agent.log. The rejected path is not collected or uploaded, but other allowed paths and script output can still be archived.

    Configured roots must resolve to accessible directories. The Machine Agent ignores an invalid root with a warning and continues using other valid roots. If no valid root remains, every action-configured log path is rejected. A path that is authorized but not found retains the existing file-not-found behavior.

    In Absolute paths to log files, enter each log file that the action should collect. If validation is enabled, each path must resolve within a directory configured in the target Agent's local allowlist. Review the Machine Agent log for rejection details.

    Retain the existing requirement that remediation scripts be stored under <machine_agent_home>/local-scripts.