Linux

The Infrastructure Agent (Infra Agent) collects host-level metrics, logs, and traces from your Linux machines and securely ships them to your Middleware account. This guide covers installation on both Debian-based and RPM-based distributions using our install scripts.

Prerequisites#

System Requirements
- CPU architectures: x86_64 and ARM
- Memory: ≥ 1 GB (agent uses ~200 MB)
- Tools: curl or wget installed on the host
Supported Distributions
- DEB-based: Ubuntu, Debian
- RPM-based: Red Hat, CentOS, Fedora, SUSE, Rocky Linux, Oracle Linux, Amazon Linux
- Other DEB/RPM distros may work but aren’t officially tested.
AWS Instances
- Use the RPM script on Red Hat or Amazon Linux instances.

Proxy users: If your host requires a proxy, set HTTP_PROXY and HTTPS_PROXY (and lowercase variants) before running the install script.

Installation#

DEB-Based Distributions (Ubuntu, Debian)

RPM-Based Distributions (Red Hat, Amazon Linux, CentOS, Fedora, etc.)

1 Run the Installer:#

1MW_API_KEY="<MW_API_KEY>" \
2MW_TARGET="https://<MW_UID>.middleware.io:443" \
3bash -c "$(curl -L https://install.middleware.io/scripts/deb-install.sh)"

2 (Optional) Add host tags:#

1MW_HOST_TAGS="env:prod,role:web" \
2MW_API_KEY="<MW_API_KEY>" \
3MW_TARGET="https://<MW_UID>.middleware.io:443" \
4bash -c "$(curl -L https://install.middleware.io/scripts/deb-install.sh)"

3 Verify installation#

1sudo systemctl status mw-agent
2sudo journalctl -u mw-agent -f    # stream live logs

1 Run the Installer:#

1MW_API_KEY="<MW_API_KEY>" \
2MW_TARGET="https://<MW_UID>.middleware.io:443" \
3bash -c "$(curl -L https://install.middleware.io/scripts/rpm-install.sh)"

2 (Optional) Add host tags:#

1MW_HOST_TAGS="env:prod,role:web" \
2MW_API_KEY="<MW_API_KEY>" \
3MW_TARGET="https://<MW_UID>.middleware.io:443" \
4bash -c "$(curl -L https://install.middleware.io/scripts/rpm-install.sh)"

3 Verify installation#

1sudo systemctl status mw-agent
2sudo journalctl -u mw-agent -f    # stream live logs

Supported Environments#

The Middleware Linux agent is distributed as standard DEB and RPM packages and runs as a regular systemd service. It does not depend on any cloud provider's APIs or services, so it works the same way on any Linux host that runs a supported distribution and can reach your Middleware account over HTTPS, including:

Public cloud virtual machines and bare metal: Amazon EC2, Microsoft Azure Virtual Machines (including Virtual Machine Scale Sets), Google Compute Engine, Oracle Cloud Infrastructure (OCI) Compute, DigitalOcean Droplets and other cloud providers.
Private cloud and on-premises: VMware vSphere, Proxmox, KVM, Hyper-V and physical servers.

Use the installer that matches the host's distribution:

Distribution family	Distributions	Installer
DEB-based	Ubuntu, Debian	DEB
RPM-based	Red Hat Enterprise Linux, CentOS, Rocky Linux, Oracle Linux, Amazon Linux, Fedora, SUSE	RPM

Both x86_64 and Arm64 architectures are supported, including Arm-based cloud instances such as AWS Graviton, Azure Cobalt, Google Axion and OCI Ampere.

Network requirements#

The agent sends data to your Middleware account over HTTPS (port 443). Make sure the host's firewall rules, security groups or network security lists allow outbound traffic to https://<YOUR_UID>.middleware.io. Hosts without direct internet access need a NAT gateway or an HTTP proxy (see Proxy users under Prerequisites).

Adding environment metadata#

To filter and group hosts by cloud provider, region or environment in Middleware, add them as host tags using MW_HOST_TAGS when you run the installer, for example:

1MW_HOST_TAGS="cloud.provider:oci,cloud.region:sa-santiago-1,env:production"

Using the OpenTelemetry Collector#

If you prefer to run the OpenTelemetry Collector instead of the Middleware agent, the OpenTelemetry Collector Contrib is also supported on any Linux host and can send host metrics, logs and traces directly to Middleware. For managed Kubernetes services such as Amazon EKS, Azure AKS, Google GKE and Oracle OKE, use the Middleware Kubernetes agent.

Zero-Code Instrumentation with OBI#

The Linux agent automatically discovers the applications running on the host, whether they run as host processes, systemd services or Docker containers, and detects the programming language of each one. You can then instrument any discovered application with OpenTelemetry eBPF Instrumentation (OBI).

OBI uses eBPF to capture traces and RED metrics (request rate, errors and duration) for HTTP, gRPC and database calls directly from the Linux kernel. No code changes, application restarts, added packages or image rebuilds are required, which makes it well suited to containerized applications whose images you cannot modify.

Requirements#

Linux kernel 5.8 or later with BTF enabled, or kernel 4.18 or later on RHEL-family distributions (Red Hat, CentOS, Rocky Linux, Oracle Linux).
The OBI agent, which the DEB and RPM installers above install automatically on supported kernels. To skip it, set MW_ENABLE_OBI=false when running the installer.

Step 1: Discover applications#

List the applications the agent has discovered on the host, along with their detected language, type (for example, systemd or docker) and listening ports:

1sudo mw-agent services list

1SERVICE ID         SERVICE NAME               LANGUAGE   TYPE      PORTS   INSTANCES   INSTRUMENTED
2e6f38b1db677d920   book-service-java          java       systemd   8086    1           -
39fff4fcb924d5413   book-service-java-docker   java       docker    8086    1           -
48d3392312658de2e   orders-api                 python     docker    8000    1           -

Use --language to filter by language (java, python, node, go, rust, php, ruby) and --all to show each running instance individually.

Step 2: Instrument an application#

Instrument an application with OBI by its service name or service ID:

1sudo mw-agent instrument --type obi --language python orders-api

All running instances (replicas) of the same application share a service ID, so they are instrumented together. Traces appear in Middleware under APM → Services within a few minutes.

Remove instrumentation#

1sudo mw-agent uninstrument --type obi orders-api

Instrumenting systemd services#

For Java, Python and Node.js applications that run as systemd services, you can also instrument them with the full OpenTelemetry language agent instead of OBI, still without code changes. The DEB and RPM installers install the required OpenTelemetry Injector by default (set MW_ENABLE_INJECTOR=false to skip it).

1sudo mw-agent instrument --type systemd --language java book-service-java

This adds a systemd drop-in that loads the language agent into the service, and restarts the service to apply it. To remove it:

1sudo mw-agent uninstrument --type systemd book-service-java

OBI captures traces at the protocol level (HTTP, gRPC and database calls). For code-level detail such as custom spans, method-level traces or continuous profiling, use the language-specific APM agents.

Service Management#

Control the mw-agent service via systemd:

Command	Description
`sudo systemctl start mw-agent`	Start the agent
`sudo systemctl stop mw-agent`	Stop the agent
`sudo systemctl restart mw-agent`	Restart the agent
`sudo systemctl status mw-agent`	Check agent status
`sudo journalctl -u mw-agent -f`	Stream live agent logs

Metrics Visibility#

Once installed, host metrics will appear under Infrastructure → Hosts in the Middleware UI within a few minutes. If no data shows up:

Confirm network connectivity to https://<YOUR_UID>.middleware.io:443.
Ensure only one Infra Agent is running per host.
Check agent logs for errors in /var/log/mw-agent/mw-agent.log or via journalctl.

Troubleshooting#

Multiple agents: Running more than one agent on the same host can cause data conflicts.
Proxy issues: Verify proxy environment variables if your host sits behind a corporate proxy.
Permission errors: Ensure you run install commands with sufficient privileges (use sudo where necessary).

Uninstall#

DEB-Based

RPM-Based

1bash -c "$(curl -L https://install.middleware.io/scripts/deb-uninstall.sh)"

1bash -c "$(curl -L https://install.middleware.io/scripts/rpm-uninstall.sh)"

Need assistance or want to learn more about Middleware? Get in touch with us via our Contact Us or join our Slack channel.