Uploaded image for project: 'Observium'
  1. Observium
  2. OBS-5332

802.1X/EAP port state from IEEE8021-PAE-MIB: discovery/poller module, device Ports > EAP tab, global page and port badge [patch, AI-assisted]

    XMLWordPrintable

Details

    Description

      Motivation

      Observium shows nothing about 802.1X port authentication on wired switches. Network teams want to see which access ports are blocked by 802.1X because a client fails to authenticate, and want to find those ports across all switches without logging in to each device.

      This patch adds a vendor independent 802.1X view based only on the standard IEEE8021-PAE-MIB (.1.0.8802.1.1.1.1). No vendor MIBs are used.

      Patch: dot1x-eap-view.patch (against trunk r15321, applies to r15420 with offsets).

      AI-assisted

      This patch was written with the help of an AI coding assistant (Claude, Anthropic), and tested on a production installation (~800 devices).

      What the patch does

      • Discovery/poller module dot1x (includes/discovery/dot1x.inc.php, includes/polling/dot1x.inc.php, shared code in includes/dot1x.inc.php)
        • Discovery checks every device for dot1xAuthConfigTable. The poller polls only devices where discovery found 802.1X ports, so devices without 802.1X cost one walk per discovery run.
        • Walks dot1xAuthConfigTable and dot1xAuthStatsTable with numeric OIDs, so no MIB file is required. The stats table is walked with -Ox so dot1xAuthLastEapolFrameSource is always hex.
        • Stores one row per port in a new table ports_dot1x (index dot1xPaePortNumber = ifIndex): PAE/backend state, controlled port control/status, timers (quiet, tx, supplicant/server timeout, max req, re-auth), EAPOL counters, last EAPOL frame version/source, time of last status change and time of last EAPOL rx activity.
        • The table is created/upgraded by the module itself (CREATE TABLE IF NOT EXISTS / ALTER TABLE). For inclusion upstream this should become a normal schema update.
        • On SNMP timeouts the last known state is kept; entries are only removed by discovery when the device authoritatively has no PAE-MIB data. Entries of deleted devices are cleaned up by discovery.
        • Optional: $config['dot1x']['log_changes'] writes an eventlog entry on authorized <-> unauthorized changes.
      • Device Ports > EAP tab (html/pages/device/ports/eap.inc.php), shown after "FDB Table" when the device has 802.1X ports: one row per port with link, 802.1X on/off, status, PAE and backend state, last EAPOL source MAC and counters, timers, time since last status change, filter "only unauthorized".
      • Global page /eap/ (html/pages/eap.inc.php): all 802.1X ports of all devices, with search form (device, 802.1X status, link state, port name/description, last EAPOL MAC) and pagination. User permissions are applied via generate_query_permitted_ng(['device', 'port']).
      • Ports > Status Breakdown menu: entries "802.1X unauthorized" and "802.1X authorized" with counts.
      • Port badge "802.1X unauthorized" in port lists (Ports > Basic/Details etc.), linking to the EAP tab, tooltip with last EAPOL activity and source MAC.

      Status rule

      Terms follow dot1xAuthAuthControlledPortStatus: authorized / unauthorized.

      Status Rule
      802.1X unauthorized (badge) ifOperStatus up AND dot1xAuthAuthControlledPortControl = auto AND dot1xAuthAuthControlledPortStatus = unauthorized AND dot1xAuthEapolFramesRx increased within the last 15 minutes
      802.1X authorized control auto AND status authorized
      802.1X off control not auto (forceAuthorized / forceUnauthorized)

      The EAPOL activity condition is important: an empty access port (link up but no client, or the client has left) also stays "unauthorized", and dot1xAuthLastEapolFrameSource is sticky. A supplicant that keeps failing keeps sending EAPOL frames, an empty port does not. Without this condition about 1400 of ~30000 802.1X ports in our network were flagged, and the ports we checked on the switch CLI had no client at all. The window is configurable: $config['dot1x']['eapol_active_period'] (seconds, default 900).

      Core changes (small hooks)

      • html/pages/device.inc.php: add the "EAP" suboption after "FDB Table" when the device has 802.1X ports.
      • html/includes/entities/port.inc.php (generate_port_row()): append the badge to $port['tags'].
      • html/includes/navbar.inc.php: add the Status Breakdown entries after "Deleted".
        All three hooks only run when includes/dot1x.inc.php exists.

      Tested with

      • Extreme ERS (BOSS): full data incl. PAE/backend state; MAC/NEAP authenticated ports are reported as authorized by the device.
      • HPE Aruba ProCurve 2920 / 5406R (16.10/16.11): port status, EAPOL counters and last source are only returned for ports where port-access authenticator is enabled; PAE/backend state are not returned (shown as "-"). Switches without enabled ports return config columns only and are correctly ignored.
      • SNMP v2c and v3, distributed setup (web + 2 pollers, remote DB).

      Known limits of the standard MIB

      • Multihost/multi-auth: the MIB has port state only. A port can be authorized while a second client on it is rejected.
      • Clients admitted by MAC authentication do not appear in the MIB. A non-802.1X device rejected by MAC authentication sends no EAPOL frames and is therefore not flagged.
      • Per-client session data exists only in vendor MIBs and is out of scope here.

      Configuration

      $config['poller_modules']['dot1x']    = 1;
      $config['discovery_modules']['dot1x'] = 1;
      // optional
      //$config['dot1x']['os_group'] = [ ... ];          // limit to OS groups (default: all devices)
      //$config['dot1x']['os']       = [ ... ];          // limit to OS names (default: all devices)
      //$config['dot1x']['eapol_active_period'] = 900;   // seconds
      //$config['dot1x']['log_changes'] = TRUE;

      For upstream inclusion the module would naturally be registered in $config['poller_modules'] / $config['discovery_modules'] defaults and the table in the schema and $config['device_tables'].

      How to test

      1. Apply the patch, enable the modules in config.php.
      2. ./discovery.php -h <switch> -m dot1x - creates the table, prints a CLI table with ifIndex, port, control, PAE, backend, status, last EAPOL MAC.
      3. ./poller.php -h <switch> -m dot1x -d
      4. Device > Ports > EAP shows the 802.1X ports; Ports > Status Breakdown shows the 802.1X counts; /eap/status=unauthorized/ lists ports with a failing client (two polls are needed before EAPOL activity is detected).

      Attachments

        Activity

          People

            landy Mike Stupalov
            FloMeyer Florian Meyer
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

              Created:
              Updated: