gomib

gomib

Go library for parsing and querying SNMP MIB files.

Supports SMIv1 and SMIv2 modules. Loads MIBs from directories, directory trees, or embedded filesystems. Resolves imports, builds the OID tree, and provides typed access to objects, types, notifications, and conformance definitions.

Install

go get github.com/golangsnmp/gomib

Requires Go 1.24+.

Quick start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/golangsnmp/gomib"
)

func main() {
    m, err := gomib.Load(context.Background(),
        gomib.WithSystemPaths(),
        gomib.WithModules("IF-MIB"),
    )
    if err != nil {
        log.Fatal(err)
    }

    obj := m.Object("ifIndex")
    if obj != nil {
        fmt.Printf("%s  %s  %s  %s\n", obj.Name(), obj.OID(), obj.Type().Name(), obj.Access())
        // ifIndex  1.3.6.1.2.1.2.2.1.1  InterfaceIndex  read-only
    }
}

Loading MIBs

// Load everything from a source (parses all files)
m, err := gomib.Load(ctx, gomib.WithSource(src))

// Load only specific modules and their transitive dependencies.
// Faster when the source contains hundreds of MIBs but you only need a few.
m, err := gomib.Load(ctx, gomib.WithSource(src), gomib.WithModules("IF-MIB", "IP-MIB"))

Sources

Dir searches a single flat directory. DirTree recursively indexes a directory tree. FS wraps an fs.FS (useful with embed.FS). Multi tries multiple sources in order.

// Single directory
src, err := gomib.Dir("/usr/share/snmp/mibs")

// Recursive tree (indexed once at construction)
src, err := gomib.DirTree("/usr/share/snmp/mibs")

// Embedded filesystem
//go:embed mibs
var mibFS embed.FS
src := gomib.FS("embedded", mibFS)

// Combine sources (first match wins)
src := gomib.Multi(systemSrc, vendorSrc)

Must variants (MustDir, MustDirTree) panic on error for use in var blocks.

Files are matched by extension: no extension, .mib, .smi, .txt, .my. Override with WithExtensions. Non-MIB files are filtered during loading by checking for DEFINITIONS and ::= in the content.

Options

gomib.Load(ctx,
    gomib.WithSource(src),
    gomib.WithSystemPaths(),                             // discover net-snmp/libsmi paths
    gomib.WithLogger(slog.Default()),                    // enable debug/trace logging
    gomib.WithStrictness(mib.StrictnessPermissive),    // strictness preset
    gomib.WithDiagnosticConfig(mib.DiagnosticConfig{   // fine-grained control
        Level:  mib.StrictnessNormal,
        FailAt: mib.SeverityError,
        Ignore: []string{"identifier-underscore"},
    }),
)

Querying

Lookup methods take a plain name and return nil if not found:

obj := m.Object("ifIndex")
node := m.Node("ifEntry")
typ := m.Type("DisplayString")

For qualified lookup, scope through the module (see Module-scoped queries below).

Other lookup methods: Node, Type, Notification, Group, Compliance, Capability.

Resolve

Resolve accepts any common format - plain name, qualified name, or numeric OID - and returns the matching node:

node := m.Resolve("ifDescr")                     // plain name
node  = m.Resolve("IF-MIB::ifDescr")             // qualified
node  = m.Resolve("1.3.6.1.2.1.2.2.1.2")        // numeric OID
node  = m.Resolve(".1.3.6.1.2.1.2.2.1.2")       // leading dot

ResolveOID converts any of those formats to a numeric OID, and also handles instance-suffixed forms:

oid, err := m.ResolveOID("IF-MIB::ifDescr.5")    // OID{1,3,6,1,2,1,2,2,1,2,5}
oid, err  = m.ResolveOID("ifDescr.5")             // same result
oid, err  = m.ResolveOID("1.3.6.1.2.1.2.2.1.2")  // numeric pass-through

ResolveOID is the inverse of FormatOID:

formatted := m.FormatOID(oid)       // "IF-MIB::ifDescr.5"
back, _   := m.ResolveOID(formatted) // round-trips to the same OID

OID lookups

For cases where you already know the format, lower-level methods avoid parsing:

oid, _ := mib.ParseOID("1.3.6.1.2.1.2.2.1.1")
node := m.NodeByOID(oid)            // exact match
node  = m.LongestPrefixByOID(oid)   // longest matching prefix

Module-scoped queries

mod := m.Module("IF-MIB")
obj := mod.Object("ifIndex")
typ := mod.Type("InterfaceIndex")

Collections

m.Objects()        // all OBJECT-TYPE definitions
m.Tables()         // tables only
m.Scalars()        // scalars only
m.Columns()        // columns only
m.Rows()           // rows only
m.Types()          // all type definitions
m.Notifications()  // all notifications
m.Groups()         // all groups
m.Compliances()    // all compliances
m.Capabilities()   // all capabilities
m.Modules()        // all loaded modules

OID tree iteration

for node := range m.Nodes() {
    fmt.Println(node.OID(), node.Name(), node.Kind())
}

// Subtree iteration
node := m.Node("ifEntry")
for child := range node.Subtree() {
    fmt.Println(child.Name())
}

Objects

Each Object carries its type, access level, status, and position in the OID tree:

obj := m.Object("ifType")

obj.Name()        // "ifType"
obj.OID()         // 1.3.6.1.2.1.2.2.1.3
obj.Kind()        // column
obj.Access()      // read-only
obj.Status()      // current
obj.Type().Name() // "IANAifType"
obj.Units()       // "" (empty if not set)
obj.Description() // "The type of interface..."

Tables

table := m.Object("ifTable")
table.IsTable()  // true

row := table.Entry()           // ifEntry
cols := row.Columns()          // [ifIndex, ifDescr, ifType, ...]
idxs := row.EffectiveIndexes() // handles AUGMENTS

for _, idx := range idxs {
    fmt.Printf("INDEX %s (implied=%v)\n", idx.Object.Name(), idx.Implied)
}

Navigate from any level: obj.Table() returns the containing table, obj.Row() returns the containing row.

Effective constraints

Constraints can be defined inline on the object or inherited through the type chain. The Effective* methods walk both:

obj.EffectiveEnums()       // enum values
obj.EffectiveBits()        // BITS values
obj.EffectiveRanges()      // value ranges
obj.EffectiveSizes()       // size constraints
obj.EffectiveDisplayHint() // display hint string

Types

Types form chains: a textual convention references a parent type, which may reference another, down to a base SMI type.

typ := m.Type("DisplayString")

typ.Name()                // "DisplayString"
typ.IsTextualConvention() // true
typ.Base()                // OCTET STRING
typ.DisplayHint()         // "255a"
typ.Sizes()               // [{0 255}]
typ.Parent().Name()       // base type reference

// Walk the chain
for t := typ; t != nil; t = t.Parent() {
    fmt.Printf("%s (base: %s)\n", t.Name(), t.Base())
}

// Effective values resolve through the chain
typ.EffectiveBase()        // underlying base type
typ.EffectiveDisplayHint() // first non-empty hint in chain
typ.EffectiveEnums()       // first non-empty enum set

Classification helpers: IsCounter(), IsGauge(), IsString(), IsEnumeration(), IsBits().

Notifications

notif := m.Notification("linkDown")

notif.Name()        // "linkDown"
notif.OID()         // 1.3.6.1.6.3.1.1.5.3
notif.Status()      // current
notif.Description() // "A linkDown trap..."

for _, obj := range notif.Objects() {
    fmt.Printf("  varbind: %s (%s)\n", obj.Name(), obj.OID())
}

Diagnostics

Loading produces diagnostics for issues found during parsing and resolution.

m, err := gomib.Load(ctx, gomib.WithSource(src))

// Check for errors
if m.HasErrors() {
    fmt.Println("errors found")
}

// Inspect all diagnostics
for _, d := range m.Diagnostics() {
    fmt.Printf("[%s] %s: %s (line %d)\n", d.Severity, d.Module, d.Message, d.Line)
}

// Check unresolved references
for _, ref := range m.Unresolved() {
    fmt.Printf("unresolved %s: %s in %s\n", ref.Kind, ref.Symbol, ref.Module)
}

Strictness levels

Four presets control how strictly MIBs are validated:

m, _ := gomib.Load(ctx, gomib.WithSource(src), gomib.WithStrictness(mib.StrictnessPermissive))

For fine-grained control, use WithDiagnosticConfig:

gomib.WithDiagnosticConfig(mib.DiagnosticConfig{
    Level:  mib.StrictnessNormal,
    FailAt: mib.SeverityError,              // fail on Error or worse
    Ignore: []string{"identifier-underscore"}, // suppress specific codes
    Overrides: map[string]mib.Severity{
        "import-not-found": mib.SeverityWarning, // downgrade to warning
    },
})

CLI

The cmd/gomib tool provides a command-line interface for MIB operations:

gomib load IF-MIB                    # load and show statistics
gomib get -m IF-MIB ifIndex          # query by name
gomib get -m IF-MIB 1.3.6.1.2.1.2   # query by OID
gomib dump IF-MIB                    # JSON output
gomib lint IF-MIB                    # check for issues
gomib find --all 'if*'               # search by pattern
gomib trace -m IF-MIB ifEntry        # trace resolution
gomib paths                          # show search paths
gomib list                           # list available modules

Use -p PATH to specify MIB search paths (repeatable). Without -p, paths are discovered from net-snmp and libsmi configuration (config files, MIBDIRS/SMIPATH env vars, standard default directories).

See cmd/gomib/README.md for full command reference.