OS definitions, best practices


First of all, let me say Hi – and thank you for being an, open and encouraging community. You’ve crafted a great product and platform to develop on.

I’ve been doing some OS definitions lately, and learned a lot in the process. There is not, currently, a lot of documentation about the process or best practices. As I read through the code, looking for clues on how to best solve a problem, I have noticed there are several, different, approaches to OS definition. I understand this is an evolving project, and that many people contribute to it, and things change over time. Moving forward, what are some “best practices” we should keep in mind when defining new, and revamping old OS definitions?

os.yaml && os.inc.php

  • under what circumstance should we use one or the other? The documentation suggests to only create yaml files; php files are not needed. Looking in includes/ tells another story. Most of the definitions appear to include both yaml and php components.

  • Many OS’s define sensors in polling/poller_module/os.inc.php. Are there plans to extend the functionality of includes/definitons/os.yaml to define those parameters for the poller (much like the discovery yaml does)?

  • Reading the original proposal for moving to yaml files, it seems like the end goal was to have all configuration for OS’s in yaml files. Is this still the trajectory? What, if anything, needs to be done to move toward that goal (if this is, in fact, the goal)?

os && variant

  • How is an OS defined?
  • How is a variant defined?
  • What relationship ~should~ exist between the two?
  • What role do the MIB informations have in defining os and variants?
  • How does one know when to create a variant, instead of an os?
    – How do you create (and maintain) a variant?

These are the questions I’ve come up with after working a few different OS types. I am more than willing to help in any way I can, I’d just like to know the best way to go about it. My hope is this will open a discussion that leads to more documentation, standardization, automation and other words that end in ation.


Hi @spencerbutler ,

Quick answer concerning the OS and variant : The variant is just defined for tests. It is in fact an instance of test for a particular model of device matching the OS.
Exemple :

  • OS : myUpsOs
  • tests:
    – variant: myUpsOs-smallUPS
    – variant: myUpsOs-bigUPS

Both models of UPS are from the same familly, use the same mib, and can share the discovery process, but probably the big UPS has more sensors than the small one. Having test data for both (using variant) ensures that no regression can occur.

If 2 devices (from the same vendor) are too different (different mibs, different logic, etc etc) then you should probably create a new OS instead of adding stuff to the 1st one.


As for all the PHP files. LibreNMS has a large codebase and when things are change we often support the old and new way of doing things. We simply can’t move all the code at once without breaking things (tests have improved this). Also, because this is a community project, people work on what they need. So if something is working, there isn’t much motivation to re-write it.