---
title: "Direct-login coverage"
description: "Check whether each server can report direct logins. Read its coverage state, fix the reason it isn't covered, and see what detection does and doesn't capture."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Direct-login coverage

Check which servers can report direct logins and why others cannot.

## How coverage affects evidence

A server reports direct logins only when it is covered. On a server that isn't covered, a quiet week proves nothing, so External access never counts it as having had no direct logins. This page explains what coverage means, how to check one server, and how to fix each reason a server isn't covered.

## What detection covers [#boundary]

| Covered | Not covered |
|---|---|
| SSH, including `ssh host command`, `scp`, `sftp` and `rsync` | Reverse shells |
| The local or cloud console | Exploited services |
| `su` | Container `exec` |
| | An SSH daemon that bypasses PAM |
| | A PAM stack whose control flow skips the hook |
| | sshd options overridden on its command line |

The same list appears under **What detection covers** in the **Direct-login detection** section on Policies → Server access, and in every evidence export. Direct-login capture works on Linux servers. It is not available on macOS or Windows.

Coverage tells you the login path is watched, not that every way onto the server is.

## What each state means [#states]

| State | Meaning |
|---|---|
| **Covered** | **Direct logins to this server are captured.** |
| **Not covered** | **Direct logins to this server are not captured, so a quiet stretch here proves nothing.** |
| **Unknown** | **Whether direct logins to this server are captured is not known. Unknown is not the same as no direct logins.** |

A server reads **Covered** only on its own Alpamon's report, and never while detection is off. Covered means Alpamon found the session hook registered for `sshd`, `login` and `su`, and `UsePAM yes` in sshd's on-disk configuration. It does not mean Alpamon checked the PAM control flow ahead of the hook, or options a running sshd was started with on its command line.

**Unknown** is neither covered nor zero logins. A server that hasn't reported, can't be checked, or runs an Alpamon too old to report coverage reads **Unknown**, and its direct logins for that time are unknown too.

To be covered, a server needs Alpamon 2.8.2 or later and `alpamon-pam` 1.1.3 or later.

On SELinux-enforcing hosts (RHEL family), `sshd` and console logins report session events only from Alpamon 2.8.4 or later and `alpamon-pam` 1.3.1 or later. Below those versions, such a server can still read **Covered**.

## Check a server [#check-a-server]

Open the server's page and go to the **Access** tab. The **Direct-login coverage** card at the top shows the state and the time of Alpamon's **Last report**. For a server that isn't covered, it adds **Reason**, **What to change** and **How to check**. Anyone who can open the server sees this card.

After you apply the fix, the state turns **Covered** on Alpamon's next report.

For coverage per server per day over a period, use External access → **Summary**: see [Summary and evidence](/use/audit/governance/external-access/evidence/#coverage).

## Reasons and fixes [#reasons]

| Reason | State | What to change | How to check |
|---|---|---|---|
| **Detection off** | **Not covered** | A policy owner turns detection on in Policies → Server access. While it is off, no server is covered | Each server's next report after detection is on |
| **alpamon-pam not installed** | **Not covered** | Install `alpamon-pam` 1.1.3 or later, for example `sudo apt-get install -y alpamon-pam` (or `yum` on RHEL-based systems). openSUSE and SLES need 1.1.5 or later, installed with `zypper` (see [PAM and sudo issues](/use/work-sessions/terminal/troubleshoot-sudo/#sudo-fails-or-asks-for-the-root-password-on-opensuse-or-sles)). It registers the session hook for `sshd`, `login` and `su` (see [Where the session hook lives](#hook-location)). Installing it also wires sudo's PAM authentication | Alpamon's next report shows the hook registered |
| **sshd: UsePAM no** | **Not covered** | Set `UsePAM yes` in sshd's configuration, then reload sshd to apply it | Alpamon reads sshd's on-disk configuration (`sshd -T`), which is what counts as effective, and reports it |
| **Session hook missing for sshd** | **Not covered** | Register the alpamon session hook in sshd's PAM stack again. See [Where the session hook lives](#hook-location) | Alpamon's next report shows the hook registered |
| **Session hook missing for login** | **Not covered** | Register the alpamon session hook in the console login's PAM stack again. See [Where the session hook lives](#hook-location) | Alpamon's next report shows the hook registered |
| **Session hook missing for su** | **Not covered** | Register the alpamon session hook in su's PAM stack again, for `su` and, where it exists, `su-l`. See [Where the session hook lives](#hook-location) | Alpamon's next report shows the hook registered |
| **Alpamon could not check the configuration** | **Unknown** | Make sure the files under `/etc/pam.d` and sshd's configuration are readable, and that the session hook is registered | Alpamon's next report |
| **Alpamon needs an upgrade** | **Unknown** | Upgrade Alpamon to 2.8.2 or later. See [Manage servers](/use/servers/manage/#agent-card). To find every server in this state, choose **See servers that need an Alpamon upgrade** under the fix, which opens the server list filtered to this reason | Alpamon's first report after the upgrade |
| **Alpamon not reporting** | **Unknown** | Reconnect Alpamon if the server is disconnected | The server's connection status, then its next report |
| **Direct login capture is not available on this operating system.** | **Unknown** | Nothing. Capture isn't available on macOS or Windows | — |

An Alpamon too old to report coverage can still show **alpamon-pam not installed** or **sshd: UsePAM no** when it sees them, but never **Covered**.

Right after detection is turned on, every server reads **Alpamon not reporting** until its next report. Turning detection off for any part of a day makes that day not covered for every server.

### Where the session hook lives [#hook-location]

`alpamon-pam` registers the session hook when you install it. Where the hook goes depends on the distribution:

- **Debian and Ubuntu**: `alpamon-pam` versions later than 1.2.1 register the hook through `pam-auth-update`, as the `alpamon` profile (`/usr/share/pam-configs/alpamon`). The hook lands in `/etc/pam.d/common-session`, which `sshd`, `login` and `su` include, so reinstalling or upgrading OpenSSH, `login` or `util-linux` leaves it in place. If `/etc/pam.d/common-session` was edited by hand, `pam-auth-update` leaves the file alone, and `alpamon-pam` puts the hook in `/etc/pam.d/sshd`, `/etc/pam.d/login`, `/etc/pam.d/su` and `/etc/pam.d/su-l` instead. Version 1.2.1 and earlier put the hook in those four files; upgrading moves it to `/etc/pam.d/common-session`. A service file that differs from the copy its package ships, for example one you customized, keeps its own hook line as well, and the installer names each such file.
- **RHEL-based and SUSE**: the hook goes in `/etc/pam.d/sshd`, `/etc/pam.d/login`, `/etc/pam.d/su` and `/etc/pam.d/su-l`.

Only SSH, the console login, `su` and `su -` report. Other programs that share the same PAM configuration, such as `sudo -i`, cron and graphical desktop logins, don't.

To put a missing hook back, run `sudo dpkg-reconfigure alpamon-pam` on Debian and Ubuntu, or reinstall `alpamon-pam` with your package manager on RHEL-based and SUSE systems.

If you turn the `alpamon` profile off in `pam-auth-update` (in its dialog on Ubuntu 22.04, or with `sudo pam-auth-update --disable alpamon` on Ubuntu 24.04), it stays off when you reinstall `alpamon-pam` or run `dpkg-reconfigure`. While it is off, only service files that kept their own hook line still report. To turn it back on, run `sudo pam-auth-update --enable alpamon`.

## Coverage across your servers [#fleet]

- **Server access policies**: the **Direct-login detection** section shows **Covered servers** as a count of covered servers out of all servers. When some servers aren't covered or are unknown, a count of servers that need a look follows it; expand it for the not-covered and unknown counts, each a link to the server list filtered to those servers, and the number of servers behind each reason.
- **Server list**: the **Coverage** filter row offers **All**, **Covered**, **Not covered** and **Unknown**. Users with the `reviewer`, `auditor`, `security_admin` or `admin` role also get a fifth choice, **Alpamon needs an upgrade**, which lists the servers whose Alpamon is too old to report coverage. The row filters by one choice at a time, so picking the reason replaces a chosen state.
- **Links to that list**: for the same roles, **See servers that need an Alpamon upgrade** appears wherever **Alpamon needs an upgrade** is shown: under the fix on a server's coverage card, in the reason breakdown on **Server access policies**, and under **Not covered, by reason** on External access → **Summary**.
- **Coverage warning**: when a covered server stops being covered while detection is on, the reviewers get a warning that names the server and the reason and links to its **Access** tab. It is sent at most once per server per day. See [Notifications](/use/audit/governance/external-access/#notifications).

## Related docs

- [External access](/use/audit/governance/external-access/)
- [Summary and evidence](/use/audit/governance/external-access/evidence/)
- [Manage servers](/use/servers/manage/)
- [PAM and sudo issues](/use/work-sessions/terminal/troubleshoot-sudo/)

Source: https://docs.alpacax.com/use/audit/governance/external-access/coverage/
