Documentation potential improvement re Aruba (and antecedents) nomenclature

[jrbinks]

With all the product lines that Aruba (HPE, 3Com, HP) have absorbed over the years, and the renaming, it is very confusing for end users.

This, I think, is a summary of the official designations (I reference them here https://github.com/jrbinks/rancid-arubaoscx ) and how they fit with snmp-info today:

• ArubaOS-CX (AOS-CX) - higher-end switching products (linux-based ) --> Layer3/ArubaCX.pm
• ArubaOS/AOS - Aruba wireless controllers/mobility access switches, the former now called Mobility Controllers/Mobility Conductors (I think, it's hard to keep up) --> Layer3/Aruba.pm
• ArubaOS-Switch/AOS-S - Modern Aruba switches (e.g, 2930F) - this is the new branding for the former traditional HP ProvisionOS --> currently Layer2/HP.pm
• Comware - Aruba/HPE Comware (nowadays "flexnetwork" but historic Comware3/5/7, derived from H3C) devices --> Layer3/H3C.pm
• 3Com Lanswitch - old 3Com products (not including early Comware3 products such as E5500 4800G) --> Layer2/3Com.pm

snmp-info (and rancid, etc) /should/ probably try and follow this convention and keep a clean separation and clear labelling of what supports what, however I do realise this is after-the-fact and may be difficult to change at this point. I'm more providing this for the sake of the archives, and perhaps it could be mentioned in a page somewhere that confused users can be pointed to.

I'd also be interested if anyone else can better summarise it!

[inphobia]

can be seen in the context of #405

for the technical part i think snmp::info modules are determined by the enterprises oid, that will determine in most cases what data & quircks you need to work with.

as for mergers etc that a clear description of the modules goes a long way to informing the user: https://github.com/netdisco/snmp-info/blob/c6c168733e512c3a02aa4d7296ea0752fd535b4f/lib/SNMP/Info/Layer2/Aerohive.pm#L321-L322

i do get the point that it can get out of control, https://github.com/netdisco/snmp-info/blob/master/lib/SNMP/Info/Layer7/Neoteris.pm being an excellent example, which is out of date since new they've been bought by ivanti.

renaming an snmp::info module after mergers might be a bit clearer, but can break stuff in weird & wonderfull ways. on the other hand in a few years we would just have 4 modules: cisco; extreme, huawei & juniper

one of the main goals of snmp:;info is to not make it matter what device you're talking to. the functions from base snmp;;info will mostly return the same data structures no matter what device is on ther other side (mocking up a complete bridge mib is done in a few modules). i tnink we do a decent job in keeping the summaries up to date for supported devices: https://metacpan.org/pod/SNMP::Info#Device-Subclasses

we also try do our best to keep our mibs complete if possible - some vendors remove eol devices related info from their mibs, if at all possible we add those again to our mibs.

summary

• i think the documentation is comprehensive enough to indicate what we support
• while some classes provide extra functions, snmp::info is there to shield you from devices with borked snmp support
• i don't have an answer for the "if, when & how" of what to do after mergers. it's rare that our modules need major changes after a merger, either khey leep the enterprises oid & the existing code, or they start fresh with at least a new oid
• for what vendor(), os() etc should return after a merger, and when to change it, oan't say. perhaps the smartest option is to see if we start getting issues issues opened for that.

[inphobia]

after letting it sink in for some time, after a few more rounds of mergers in the networking world, and after stealing your rancid code :) , after looking at the foundry module & thinking that it might need a rework for "layer 3 images", which are the only option since os version 10, i can understand your point of view.

on the other hand, having to change module names in snmp::info for every merger seems overkill, perhaps even pointless & adding to the confusion. not to mention that almost all modules hardcode vendor() & os().

with snmp::info growing the wall of text that is https://metacpan.org/pod/SNMP::Info#SUBCLASSES is growing to the point it's hard to get an overview.

so i'll make a proposal:

• we strip all mentions of vendor/os/mib from the main snmp::info subclasses page
• the actual module man pages are for most cases quite uniform, they can be extented with a way to list, as in your example, which specific devices (either by os name, product line name, whatever...) the product is know in the market. and most likely , if know, a list of all previous owners (brocade? no, foundry? no, ruckus? no, commscope)
• once the info is uniformly enough formatted, add a github action or extend the build script to go through those perldoc keys & compile a list of operating system names, vendors, products & mibs to and create 1 overview of what is supported where. if a module hardcodes vendor() or os() then it can also make a mention of where you'll find your device in netdisco's overview

it might still be a huge list, but at least the relevant info is in one place that way, we don't need to duplicate anything or remember to update it in several places. it also is not really a very intrusive change, we can leave module names since it will be less relevant in figuring out what's supported, just point to the generated overview.

is it the ideal way to handle this? perhaps not, vendor() & os() handling isn't really addressed, just given more context. adding new names, vendors, etc would still be a manual job most of the time. product lines that either support multiple os'es or use different modules depening on their version is not addressed at the core. but i don't see a decent solution for these issues that does not creare recurring work or recurring confusion.

summary:

• strip main snmp::info to only show subclasses, but no details
• fix up perldoc the be uniform enough that it can be used a single source of truth for what's supported
• add github action or build extension to generate overview perldoc

i'm welcoming comments and vetos or approvals. and if this is the way to go i'll commit my time to implementing the above steps. could take a bit, but seems doable.

[jrbinks]

As a possible alternative, and I'm not necessarily saying I think this is a good idea but throwing it out there ... rather than putting the list of supported OS/versions etc in the perldoc for the module itself, simply put a placeholder referring to a page in the wiki for more info, and maintain it there, where it can be changed on a more ad-hoc basis independently of the code (for example, when we discover ostensibly a "later version" is actually implemented completely differently and needs a new approach/new module etc).

Some might rail against this idea saying that the perldoc for the module is the right place for all this, and I'm not saying that's wrong either :). But that brings the added complication of getting it in to all those perldocs, and then getting it out again to summarise it somewhere.