Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions OPTICAL-DISCOVERY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Optional Arista optical media discovery

Some Arista switches report an empty or unrecognized MAU-MIB media type even when
ENTITY-MIB identifies the installed transceiver. The existing switch SNMP poll can
optionally use those descriptions as a fallback. Valid MAU classifications always
take precedence. Other vendors and switches outside the allowlist are unchanged.

Disabled by default. Set these environment variables and rebuild the application
configuration cache using the normal deployment workflow:

```
IXPM_OPTICS_ENABLED=true
IXPM_OPTICS_SWITCH_IDS=1,2,3
```

Use your installation's switch IDs. A nonempty list takes precedence over the
legacy single-ID setting `IXPM_OPTICS_SWITCH_ID`. The vendor name must be Arista
(case-insensitive).

Exact Ethernet interface names take precedence; a breakout interface can inherit
from its immediate physical parent only. Unknown or conflicting descriptions are
ignored. When ENTITY-MIB polling fails, an existing known classification is retained
if MAU-MIB is empty; the warning contains a generic error, not the SNMP exception.
A successful empty inventory is distinct from a failed poll. Physical transceiver
removal has not been hardware-tested.

Pilot one switch with a non-saving poll, then compare a normal poll against a saved
inventory baseline before enabling more switches. Check port identity, interface
index, speed and media. To disable, set `IXPM_OPTICS_ENABLED=false` and rebuild the
configuration cache. Disabling discovery does not undo previously saved media values.

Originally released at https://github.com/repstein2/ixpmanager-optical-discovery.
The released implementation was validated on IXP Manager 7.3.1 across 28 Arista
switches at three Community IX exchanges, populating 204 previously empty media
values with no unexpected identity/count/index/speed changes in the recorded
baseline comparisons. This is historical deployment evidence, not a live test of
the current upstream revision. DWDM wavelength/frequency discovery, OSFP,
IPv6-only SNMP management, and 800G/1.6T hardware are outside the validated scope.

See `tests/Optics/README.md` for the synthetic regression commands and limitations.
41 changes: 39 additions & 2 deletions app/Models/SwitchPort.php
Original file line number Diff line number Diff line change
Expand Up @@ -445,10 +445,11 @@ public function ifnameToSNMPIdentifier(): string|null
* @param SNMP $host An instance of the SNMP host object
* @param bool $logger An instance of the logger or false
*
* @throws
*/
public function snmpUpdate( SNMP $host, bool $logger = false, bool $nosave = false ): static
public function snmpUpdate( SNMP $host, bool $logger = false, bool $nosave = false, ?string $entityMedia = null, bool $opticDiscoveryFailed = false ): static
{
$previousMauType = $this->mauType;

foreach( self::$SNMP_MAP as $snmp => $attribute ) {

switch( $snmp ) {
Expand Down Expand Up @@ -533,6 +534,42 @@ public function snmpUpdate( SNMP $host, bool $logger = false, bool $nosave = fal

} catch( \Exception $e ){}

// Use ENTITY-MIB only when MAU cannot identify the media.
if (
$entityMedia !== null
&& (
$this->mauType === '(empty)'
|| str_starts_with(
$this->mauType ?? '',
'(unknown type - oid:'
)
)
) {
if ($previousMauType !== $entityMedia && $logger) {
Log::info(
"[{$this->switcher->name}]:{$this->name} "
. "ENTITY-MIB media changed from "
. "[{$previousMauType}] to [{$entityMedia}]"
);
}

$this->mauType = $entityMedia;

} elseif (
$opticDiscoveryFailed
&& $this->mauType === '(empty)'
&& is_string($previousMauType)
&& $previousMauType !== ''
&& $previousMauType !== '(empty)'
&& !str_starts_with(
$previousMauType,
'(unknown type - oid:'
)
) {
// Preserve a previously known value during discovery failure.
$this->mauType = $previousMauType;
}

$this->lastSnmpPoll = now();

if( !$nosave ) {
Expand Down
71 changes: 70 additions & 1 deletion app/Models/Switcher.php
Original file line number Diff line number Diff line change
Expand Up @@ -375,6 +375,50 @@ public function snmpPollSwitchPorts( SNMP $host, bool $logger = false, bool|arra
// clone the ports currently known to this switch as we'll be playing with this array
$existingPorts = clone $this->switchPorts;

// Optional Arista ENTITY-MIB media discovery.
$opticMedia = [];
$opticDiscoveryFailed = false;

if (
config('optics.enabled', false)
&& in_array(
(int) $this->id,
array_map(
'intval',
array_filter(
array_map(
'trim',
explode(
',',
(string) (
config('optics.switch_ids')
?: config('optics.switch_id', 0)
)
)
),
fn($id) => ctype_digit($id) && (int) $id > 0
)
),
true
)
&& strcasecmp(trim($this->vendor?->name ?? ''), 'Arista') === 0
) {
$discovery = \IXP\Optics\TransceiverDiscovery::discoverWithStatus(
$host,
true
);

$opticMedia = $discovery['media'];
$opticDiscoveryFailed = !$discovery['success'];

if ($opticDiscoveryFailed) {
Log::warning(
"ENTITY-MIB discovery failed for {$this->name}: "
. ($discovery['error'] ?? 'Unknown error')
);
}
}

$foundIfIndexes = [];

// iterate over all the ports discovered on the switch:
Expand Down Expand Up @@ -432,7 +476,32 @@ public function snmpPollSwitchPorts( SNMP $host, bool $logger = false, bool|arra
}

// update / set port details from SNMP
$sp->snmpUpdate( $host, $logger, $nosave );
$ifName = $host->useIface()->names()[$index] ?? '';
$entityMedia = null;

// Match exact interface or its immediate physical parent.
// Never climb multiple levels in the interface hierarchy.
if (preg_match('/^Ethernet[0-9]+(?:\/[0-9]+)*$/', $ifName)) {
if (isset($opticMedia[$ifName])) {
$entityMedia = $opticMedia[$ifName];
} elseif (str_contains($ifName, '/')) {
$parent = substr(
$ifName,
0,
strrpos($ifName, '/')
);

$entityMedia = $opticMedia[$parent] ?? null;
}
}

$sp->snmpUpdate(
$host,
$logger,
$nosave,
$entityMedia,
$opticDiscoveryFailed
);
}

if( $existingPorts->count() ) {
Expand Down
55 changes: 55 additions & 0 deletions app/Optics/AristaTransceiverParser.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<?php

namespace IXP\Optics;

class AristaTransceiverParser
{
/**
* Parse ENTITY-MIB descriptions into physical-port media mappings.
*
* @param array $descriptions entPhysicalDescr records
* @return array<string, string>
*/
public static function parse(array $descriptions): array
{
$result = [];
$conflicts = [];

foreach ($descriptions as $description) {
if (!is_string($description)) {
continue;
}

if (!preg_match(
'~^Xcvr for (Ethernet[0-9]+(?:/[0-9]+)*):.*?\bmedia\s+([A-Za-z0-9][A-Za-z0-9._+-]*)\s*$~i',
trim($description),
$matches
)) {
continue;
}

$port = $matches[1];
$media = $matches[2];

// Ignore switch-reported unknown optical classifications.
if (preg_match('/^Unknown(?:Optical.*)?$/i', $media)) {
continue;
}

if (isset($result[$port]) && $result[$port] !== $media) {
$conflicts[$port] = true;
continue;
}

if (!isset($conflicts[$port])) {
$result[$port] = $media;
}
}

foreach (array_keys($conflicts) as $port) {
unset($result[$port]);
}

return $result;
}
}
65 changes: 65 additions & 0 deletions app/Optics/TransceiverDiscovery.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
<?php

namespace IXP\Optics;

use OSS_SNMP\SNMP;

class TransceiverDiscovery
{
/**
* Discover transceiver media from Arista ENTITY-MIB.
*
* Distinguishes successful empty inventory from polling failure.
*
* @return array{success: bool, media: array<string,string>, error: ?string}
*/
public static function discoverWithStatus(
SNMP $host,
bool $isArista
): array {
if (!$isArista) {
return [
'success' => false,
'media' => [],
'error' => 'Unsupported vendor',
];
}

try {
$descriptions = $host->useEntity()->physicalDescription();

if (!is_array($descriptions)) {
return [
'success' => false,
'media' => [],
'error' => 'Invalid ENTITY-MIB response',
];
}

return [
'success' => true,
'media' => AristaTransceiverParser::parse($descriptions),
'error' => null,
];

} catch (\Throwable $e) {
return [
'success' => false,
'media' => [],
'error' => 'SNMP ENTITY-MIB query failed',
];
}
}

/**
* Backward-compatible discovery method.
*
* @return array<string,string>
*/
public static function discover(
SNMP $host,
bool $isArista
): array {
return self::discoverWithStatus($host, $isArista)['media'];
}
}
10 changes: 10 additions & 0 deletions config/optics.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<?php

return [
'enabled' => env('IXPM_OPTICS_ENABLED', false),
'switch_id' => env('IXPM_OPTICS_SWITCH_ID', 0),

// Optional comma-separated list of enabled switch IDs.
'switch_ids' => env('IXPM_OPTICS_SWITCH_IDS', ''),

];
18 changes: 18 additions & 0 deletions tests/Optics/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Arista optical media discovery regressions

From the repository root:

```
IXPM_SOURCE_DIR="$PWD" php tests/Optics/standalone/test-parser.php
IXPM_SOURCE_DIR="$PWD" php tests/Optics/standalone/test-discovery.php
php tests/Optics/standalone/test-interface-mapping.php
```

These dependency-free synthetic checks exercise the parser and discovery status
handling. The interface-mapping test exercises a copy of the matching algorithm;
it does not replace a database-backed `Switcher::snmpPollSwitchPorts()` integration
test. The discovery test defines an isolated SNMP stub and must run in its own PHP
process, outside the application autoloader.

No tests connect to switches or require production credentials. Physical removal,
OSFP, IPv6-only SNMP management, and 800G/1.6T hardware have not been validated.
Loading