---
title: Exim
description: Exim integration to monitor mail queues
breadcrumbs: Docs > Integrations > Exim
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Exim
Supported OS Integration version1.2.0
{% callout %}
# Important note for users on the following Datadog sites: us2.ddog-gov.com

{% alert level="info" %}
To find out if this integration is available in your organization, see your [Datadog Integrations](https://app.datadoghq.com/integrations) page or ask your organization administrator.

To initiate an exception request to enable this integration for your organization, email [support@ddog-gov.com](mailto:support@ddog-gov.com).
{% /alert %}

{% /callout %}

## Overview{% #overview %}

This check monitors [Exim](https://www.exim.org/) through the Datadog Agent. It runs `exim -bp` once, summarizes the queue with `exiqsumm`, and reports the size, volume, age and number of frozen entries of the mail queue per recipient domain. It also reports whether the Exim systemd unit is running.

## Setup{% #setup %}

Follow the instructions below to install and configure this check for an Agent running on a host. For containerized environments, see the [Autodiscovery Integration Templates](https://docs.datadoghq.com/agent/kubernetes/integrations.md) for guidance on applying these instructions.

### Installation{% #installation %}

For Agent v7.21+ / v6.21+, follow the instructions below to install the exim check on your host. See [Use Community Integrations](https://docs.datadoghq.com/agent/guide/use-community-integrations.md) to install with the Docker Agent or earlier versions of the Agent.

1. Run the following command to install the Agent integration:

   ```shell
   datadog-agent integration install -t datadog-exim==<INTEGRATION_VERSION>
   ```

1. Configure your integration similar to core [integrations](https://docs.datadoghq.com/getting_started/integrations.md).

### Prerequisites{% #prerequisites %}

The check runs `exim -bp` and pipes its output through `exiqsumm`, so both utilities must be installed on the host. The check uses the absolute paths `/usr/sbin/exim` and `/usr/sbin/exiqsumm` by default because the `PATH` the check runs with does not always include `/usr/sbin`, for example when the check is run manually from a non-root shell. Set `exim_path` and `exiqsumm_path` if your installation uses other locations.

#### Queue listing permissions{% #queue-listing-permissions %}

Exim only allows admin users to list the queue while the `queue_list_requires_admin` option is enabled, which is the default. Exim treats root, the Exim user, members of the Exim group and members of the groups in `admin_groups` as admin users. On a default installation `exim -bp` therefore fails for the Agent user and the check reports `exim.returns.output` as `CRITICAL` with the error from Exim:

- Exim 4.96 and earlier: `exim: permission denied`
- Exim 4.97 and later: `exim: permission denied; not admin`

Choose one of the following options:

- **Use sudo (recommended).** Set `use_sudo: true` in the check configuration. The check then runs `sudo -n /usr/sbin/exim -bp`, which fails immediately instead of prompting for a password when sudo is not set up. Grant the Agent user passwordless `sudo` for exactly this command by adding the following line to `/etc/sudoers` (for example with `visudo`). Adjust the path if you changed `exim_path`:

  ```text
  dd-agent ALL=(root) NOPASSWD:/usr/sbin/exim -bp
  ```

On Red Hat based systems, also add:

  ```text
  Defaults:dd-agent !requiretty
  ```

This is the narrowest option: the rule only allows listing the queue.

- **Add the Agent user to the Exim group.** For example `usermod -aG Debian-exim dd-agent` on Debian and Ubuntu, or `usermod -aG exim dd-agent` on Red Hat based systems, then restart the Agent. No sudo is needed, but Exim has no read-only admin role: the Agent user also gets every other admin privilege, such as removing, freezing or forcing delivery of queued messages.

- **Disable `queue_list_requires_admin`** in the Exim configuration. This lets any local user list the queue, including sender and recipient addresses, so only do this when that is acceptable for your environment.

### Configuration{% #configuration %}

1. Edit the `exim.d/conf.yaml` file, in the `conf.d/` folder at the root of your Agent's configuration directory to start collecting your exim performance data. See the [sample exim.d/conf.yaml](https://github.com/DataDog/integrations-extras/blob/master/exim/datadog_checks/exim/data/conf.yaml.example) for all available configuration options.

   ```yaml
   init_config:
   
   instances:
     - use_sudo: true
       ## Uncomment if the binaries are not in /usr/sbin
       # exim_path: /usr/sbin/exim
       # exiqsumm_path: /usr/sbin/exiqsumm
   ```

1. [Restart the Agent](https://docs.datadoghq.com/agent/guide/agent-commands.md#start-stop-and-restart-the-agent).

### Validation{% #validation %}

[Run the Agent's status subcommand](https://docs.datadoghq.com/agent/guide/agent-commands.md#agent-status-and-information) and look for `exim` under the Checks section. A healthy run reports `Metric Samples: Last Run: 2` or more and the `exim.returns.output` service check as `OK`.

`exiqsumm` always prints a `TOTAL` summary row, so the `exim.queue.count` and `exim.queue.volume` metrics with the tag `domain:TOTAL` are submitted on every successful run, with a value of `0` when the queue is empty. If these metrics are missing, the command did not run; check the service check message and the Agent log for the error reported by `exim` or `sudo`, such as `sudo: a password is required` when the sudoers rule is missing.

To verify the command outside the Agent, run it as the Agent user:

```shell
sudo -u dd-agent /bin/sh -c 'sudo -n /usr/sbin/exim -bp | /usr/sbin/exiqsumm'
```

## Data Collected{% #data-collected %}

### Metrics{% #metrics %}

|  |
|  |
| **exim.queue.count**(gauge)        | The number of messages in a given mail queue*Shown as unit*                                                                      |
| **exim.queue.frozen.count**(gauge) | Number of recipients of frozen messages in a given mail queue, counted per recipient domain like exim.queue.count*Shown as unit* |
| **exim.queue.volume**(gauge)       | The volume of messages in a given mail queue*Shown as byte*                                                                      |
| **exim.queue.oldest_age**(gauge)  | Approximate age of the oldest message in a given mail queue, with a resolution of minutes, hours or days*Shown as second*        |

Metrics are tagged with `domain:<RECIPIENT_DOMAIN>`. The `domain:TOTAL` series summarizes the whole queue. Like `exiqsumm`, the counts are per undelivered recipient, so a message to two domains is counted once for each domain.

- `exim.queue.count` and `exim.queue.volume`: the number of queued recipients and their volume in bytes, converted from the `KB` and `MB` values that `exiqsumm` rounds to.
- `exim.queue.oldest_age`: the age in seconds of the oldest queued message. Exim reports ages in minutes up to 90 minutes, in rounded hours up to 72 hours and in rounded days beyond that, so the value has the same resolution.
- `exim.queue.frozen.count`: the number of queued recipients of frozen messages. Exim does not retry frozen messages until they are thawed or removed, so a value above `0` usually needs attention. For recipient domains longer than 78 characters the value can be too low, because `exiqsumm` truncates the domain column.

### Events{% #events %}

The Exim integration does not include any events.

### Service Checks{% #service-checks %}

**exim.returns.output**

Returns `CRITICAL` if the Agent is unable to run the command to retrieve the exim queue state.

*Statuses: ok, critical*

**exim.service.running**

Returns `OK` if the Exim systemd unit is active, `CRITICAL` if it is in any other state, and `UNKNOWN` if no Exim unit is found or systemd is not available.

*Statuses: ok, critical, unknown*

`exim.service.running` reports the state of the Exim systemd unit, using `systemctl show -p LoadState,ActiveState <unit>`:

- `OK` when the unit is `active`.
- `CRITICAL` when the unit exists but is in any other state, such as `inactive` or `failed`.
- `UNKNOWN` when no Exim unit is found or `systemctl` is not available, for example on hosts without systemd. Queue metrics are still collected.

When `service_name` is not set, the check tries the `exim4` unit (Debian, Ubuntu) and then `exim` (Red Hat based systems).

The core [systemd integration](https://docs.datadoghq.com/integrations/systemd.md) monitors any systemd unit, including Exim, with more detail. `exim.service.running` is a convenience for hosts where Exim is the only unit you want to monitor.

## Troubleshooting{% #troubleshooting %}

Need help? Contact [Datadog support](https://docs.datadoghq.com/help/).