---
title: "Linux"
description: "Set up Middleware Monitoring Agent on Linux (DEB/RPM) for efficient system monitoring and enhanced infrastructure visibility."
section: "Agent Installation"
breadcrumb: "Linux > Linux"
canonical: "https://docs.middleware.io/get-started/agent/linux"
---
# Linux

The Middleware Infrastructure Agent collects telemetry from Linux hosts so you can monitor resource usage and investigate host performance. Configured log collection and application instrumentation add context from logs and traces.

Use this integration to monitor Linux hosts, including resource utilization, system activity, logs, and application telemetry.

## Prerequisites

1. **System Requirements**

   - **CPU architectures**: x86_64 and ARM
   - **Memory**: ≥ 1 GB (agent uses ~200 MB)
   - **Required Tools**: curl or wget installed on the host
2. **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.

**Note:**

- If the host connects to the internet through a proxy, configure the proxy environment variables before running the installation script:, set HTTP_PROXY , HTTPS_PROXY (and lowercase variants)
- Make sure the proxy allows outbound connections to Middleware.

## Installation

#### DEB-Based Distributions (Ubuntu, Debian)

#### 1 Run the Installer:

```bash
    MW_API_KEY="your-initial-token" \
MW_TARGET="your-initial-uid" \
bash -c "$(curl -L https://install.middleware.io/scripts/deb-install.sh)"
```

#### 2 (Optional) Add host tags:

```bash
    MW_HOST_TAGS="env:prod,role:web" \
MW_API_KEY="your-initial-token" \
MW_TARGET="your-initial-uid" \
bash -c "$(curl -L https://install.middleware.io/scripts/deb-install.sh)"
```

#### 3 Verify installation

```bash
    sudo systemctl status mw-agent
sudo journalctl -u mw-agent -f    # stream live logs
```

![Linux Agent](/images/v2/agents/linux/linux-image.png)

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

#### 1 Run the Installer:

```bash
    MW_API_KEY="your-initial-token" \
MW_TARGET="your-initial-uid" \
bash -c "$(curl -L https://install.middleware.io/scripts/rpm-install.sh)"
```

#### 2 (Optional) Add host tags:

```bash
    MW_HOST_TAGS="env:prod,role:web" \
MW_API_KEY="your-initial-token" \
MW_TARGET="your-initial-uid" \
bash -c "$(curl -L https://install.middleware.io/scripts/rpm-install.sh)"
```

#### 3 Verify installation

```bash
    sudo systemctl status mw-agent
sudo 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](#prerequisites) 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](/get-started/agent/linux/azure-vmss)), 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](#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](#installation), for example:

```bash
MW_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](/get-started/agent/otel-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](/get-started/agent/kubernetes).

## 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)](https://opentelemetry.io/docs/zero-code/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:

```bash
sudo mw-agent services list
```

```text
SERVICE ID         SERVICE NAME               LANGUAGE   TYPE      PORTS   INSTANCES   INSTRUMENTED
e6f38b1db677d920   book-service-java          java       systemd   8086    1           -
9fff4fcb924d5413   book-service-java-docker   java       docker    8086    1           -
8d3392312658de2e   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:

```bash
sudo 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**](https://app.middleware.io/apm/services) within a few minutes.

### Remove instrumentation

```bash
sudo 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).

```bash
sudo 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:

```bash
sudo mw-agent uninstrument --type systemd book-service-java
```

> **Note:** 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](/get-started/apm).

## Manage the agent (Commands)

Middleware agent runs as a systemd service in Linux based systems, usually on Linux systems, the Middleware Agent runs as a systemd service. The service definition is typically located under:

`/usr/lib/systemd/system/`

Use the following commands to start, stop, restart, and check the status of the Middleware Agent.

| 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 |

## Verify data collection

After installing the Agent, allow a few moments for the host to start reporting telemetry.

Go to [**Infrastructure Monitoring → Hosts**](https://app.middleware.io/infrastructure/host) and verify that your Linux host appears and is reporting metrics.

After data collection starts, you can:

- View host metrics in [Infrastructure Monitoring](https://app.middleware.io/infrastructure/).
- View collected host logs in [Log Monitoring](https://app.middleware.io/logs).
- Create [alerts](/features/alerts) for collected metrics.
- Create [custom dashboards](/features/dashboards) to visualize Linux host metrics.

## Uninstall

#### DEB-Based

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

#### RPM-Based

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

## Troubleshooting

**Data is not coming after agent installation?**

It may take a few moments for telemetry to appear after a new Agent installation.
First, go to [Infrastructure Monitoring → Hosts](https://app.middleware.io/infrastructure/host) and check whether the host is reporting data.

If the host does not appear or data is not being collected, check the following:

- **Check network connectivity.**
  Verify that the host can establish an outbound HTTPS connection to:
  `https://<YOUR_UID>.middleware.io:443`
- **Check for multiple Agents.**
  Make sure only one Middleware Infrastructure Agent is running on the host.
- **Check Agent logs.**
  Review the Agent log file for errors:
  `/var/log/mw-agent/mw-agent.log`
  You can also inspect the service logs using `journalctl`.
- **Check proxy configuration.**
  If the host is behind a corporate proxy, verify that the required `HTTP_PROXY` and `HTTPS_PROXY` environment variables are configured correctly and that the proxy allows connections to Middleware.
- **Check permissions.**
  Make sure the installation and Agent management commands are run with sufficient privileges. Use sudo where required.
- Deep troubleshooting.
  For deeper troubleshooting, see the [MW Linux Agent Troubleshooting Guide](https://github.com/middleware-labs/mw-agent-troubleshooting-guide/wiki/mw%E2%80%90linux%E2%80%90agent%E2%80%90troubleshooting%E2%80%90guide).

If you’re still unsure about the issue, you may reach out to Middleware support team via the chatbot (which you are seeing at the bottom-right corner of this page) or email **support{at}middleware{dot}io**

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