diff --git a/OPTICAL-DISCOVERY.md b/OPTICAL-DISCOVERY.md new file mode 100644 index 000000000..57599412f --- /dev/null +++ b/OPTICAL-DISCOVERY.md @@ -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. diff --git a/app/Models/SwitchPort.php b/app/Models/SwitchPort.php index 4c29946c7..1d3d884b5 100644 --- a/app/Models/SwitchPort.php +++ b/app/Models/SwitchPort.php @@ -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 ) { @@ -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 ) { diff --git a/app/Models/Switcher.php b/app/Models/Switcher.php index 59d80d255..6a5b51318 100644 --- a/app/Models/Switcher.php +++ b/app/Models/Switcher.php @@ -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: @@ -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() ) { diff --git a/app/Optics/AristaTransceiverParser.php b/app/Optics/AristaTransceiverParser.php new file mode 100644 index 000000000..36b3f03d0 --- /dev/null +++ b/app/Optics/AristaTransceiverParser.php @@ -0,0 +1,55 @@ + + */ + 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; + } +} diff --git a/app/Optics/TransceiverDiscovery.php b/app/Optics/TransceiverDiscovery.php new file mode 100644 index 000000000..928bb3da2 --- /dev/null +++ b/app/Optics/TransceiverDiscovery.php @@ -0,0 +1,65 @@ +, 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 + */ + public static function discover( + SNMP $host, + bool $isArista + ): array { + return self::discoverWithStatus($host, $isArista)['media']; + } +} diff --git a/config/optics.php b/config/optics.php new file mode 100644 index 000000000..a30da9726 --- /dev/null +++ b/config/optics.php @@ -0,0 +1,10 @@ + 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', ''), + +]; diff --git a/tests/Optics/README.md b/tests/Optics/README.md new file mode 100644 index 000000000..b0d3bbb20 --- /dev/null +++ b/tests/Optics/README.md @@ -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. diff --git a/tests/Optics/standalone/test-discovery.php b/tests/Optics/standalone/test-discovery.php new file mode 100644 index 000000000..9d7240da3 --- /dev/null +++ b/tests/Optics/standalone/test-discovery.php @@ -0,0 +1,132 @@ +snmp->fail) { + throw new \RuntimeException( + 'TEST_SECRET_DO_NOT_LOG' + ); + } + return $this->snmp->data; + } + }; + } + } +} + +namespace { + +$sourceDir = getenv('IXPM_SOURCE_DIR'); + +if (!$sourceDir || !is_dir($sourceDir)) { + fwrite(STDERR, + "ERROR: Set IXPM_SOURCE_DIR to a patched IXP Manager checkout.\n" + ); + exit(2); +} + + require getenv('IXPM_SOURCE_DIR') + . '/app/Optics/AristaTransceiverParser.php'; + + require getenv('IXPM_SOURCE_DIR') + . '/app/Optics/TransceiverDiscovery.php'; + + use OSS_SNMP\SNMP; + use IXP\Optics\TransceiverDiscovery; + + $snmp = new SNMP(); + $failed = 0; + + function check( + string $name, + bool $ok + ): void { + global $failed; + + echo ($ok ? 'PASS: ' : 'FAIL: ') + . $name . PHP_EOL; + + if (!$ok) { + $failed++; + } + } + + $snmp->data = [ + 'Xcvr for Ethernet1: model TEST type QSFP-DD media 400GBASE-ZR', + 'Xcvr for Ethernet2: model TEST type SFP media Unknown' + ]; + + $r = TransceiverDiscovery::discoverWithStatus( + $snmp, true + ); + + check( + 'Recognized optic', + $r['success'] === true + && $r['media'] === [ + 'Ethernet1' => '400GBASE-ZR' + ] + ); + + $snmp->data = []; + + $r = TransceiverDiscovery::discoverWithStatus( + $snmp, true + ); + + check( + 'Successful empty inventory', + $r['success'] === true + && $r['media'] === [] + ); + + $r = TransceiverDiscovery::discoverWithStatus( + $snmp, false + ); + + check( + 'Unsupported vendor rejected', + $r['success'] === false + && $r['media'] === [] + ); + + $snmp->data = ['invalid' => new \stdClass()]; + + $r = TransceiverDiscovery::discoverWithStatus( + $snmp, true + ); + + check( + 'Malformed entry ignored', + $r['success'] === true + && $r['media'] === [] + ); + + $snmp->fail = true; + + $r = TransceiverDiscovery::discoverWithStatus( + $snmp, true + ); + + check( + 'SNMP exception handled', + $r['success'] === false + && $r['media'] === [] + && $r['error'] === 'SNMP ENTITY-MIB query failed' + && !str_contains(json_encode($r), 'TEST_SECRET_DO_NOT_LOG') + ); + + echo "\nFailures: $failed\n"; + exit($failed === 0 ? 0 : 1); +} diff --git a/tests/Optics/standalone/test-interface-mapping.php b/tests/Optics/standalone/test-interface-mapping.php new file mode 100644 index 000000000..248f88361 --- /dev/null +++ b/tests/Optics/standalone/test-interface-mapping.php @@ -0,0 +1,65 @@ + '100GBASE-LR4', + 'Ethernet8/1' => '400GBASE-AR8', + 'Ethernet8/3' => '400GBASE-SR8', + 'Ethernet23' => 'AMP-ZR', + 'Ethernet40' => '400GBASE-ZR', +]; + +$cases = [ + ['Exact nested match', 'Ethernet8/1', '400GBASE-AR8'], + ['Second nested match', 'Ethernet8/3', '400GBASE-SR8'], + ['Base interface match', 'Ethernet8', '100GBASE-LR4'], + ['Parent fallback', 'Ethernet23/1', 'AMP-ZR'], + ['Unrelated interface', 'Ethernet24/1', null], + ['Non-Ethernet interface', 'Management1', null], + ['Unknown interface', 'Ethernet99', null], + ['Immediate parent only', 'Ethernet23/1/2', null], + ['Exact match precedence', 'Ethernet8/1/1', '400GBASE-AR8'], + ['No prefix collision', 'Ethernet4', null], +]; + +$failures = 0; + +foreach ($cases as [$name, $interface, $expected]) { + $actual = resolveMedia($interface, $optics); + + if ($actual === $expected) { + echo "PASS: $name\n"; + } else { + echo "FAIL: $name\n"; + $failures++; + } +} + +echo "\nTests: " . count($cases) . "\n"; +echo "Failures: $failures\n"; + +exit($failures === 0 ? 0 : 1); diff --git a/tests/Optics/standalone/test-parser.php b/tests/Optics/standalone/test-parser.php new file mode 100644 index 000000000..ea44d4b09 --- /dev/null +++ b/tests/Optics/standalone/test-parser.php @@ -0,0 +1,93 @@ + [ + [ + 'Xcvr for Ethernet8/1: model TEST type QSFP-DD media 400GBASE-AR8', + 'Xcvr for Ethernet8/3: model TEST type QSFP-DD media 400GBASE-SR8', + ], + [ + 'Ethernet8/1' => '400GBASE-AR8', + 'Ethernet8/3' => '400GBASE-SR8', + ], + ], + + '10G DWDM' => [ + [ + 'Xcvr for Ethernet1: model SFP-10GDWER-39 type SFP media 10GBASE-ER', + 'Xcvr for Ethernet2: model SFP-10GDWZR-27 type SFP media Unknown', + ], + [ + 'Ethernet1' => '10GBASE-ER', + ], + ], + + '400G coherent optics' => [ + [ + 'Xcvr for Ethernet25: model QDD-400G-ZR type QSFP-DD media 400GBASE-ZR', + ], + [ + 'Ethernet25' => '400GBASE-ZR', + ], + ], + + 'Arista optical amplifier' => [ + [ + 'Xcvr for Ethernet23: model QSFP-AMP-ZR type QSFP media AMP-ZR', + ], + [ + 'Ethernet23' => 'AMP-ZR', + ], + ], + + 'Unknown classifications' => [ + [ + 'Xcvr for Ethernet3: model TEST type SFP media Unknown', + 'Xcvr for Ethernet4: model TEST type SFP media UnknownOptical10G', + ], + [], + ], + + 'Conflicting descriptions' => [ + [ + 'Xcvr for Ethernet5: model TEST type QSFP media 100GBASE-LR4', + 'Xcvr for Ethernet5: model TEST type QSFP media 100GBASE-SR4', + ], + [], + ], +]; + +$failed = 0; + +foreach ($cases as $name => [$descriptions, $expected]) { + $actual = AristaTransceiverParser::parse($descriptions); + + if ($actual === $expected) { + echo "PASS: $name\n"; + } else { + echo "FAIL: $name\n"; + $failed++; + } +} + +echo "\nTests: " . count($cases) . "\n"; +echo "Failures: $failed\n"; + +exit($failed === 0 ? 0 : 1);