Documentation
¶
Overview ¶
Package gomib loads and resolves SNMP MIB modules.
Call Load with one or more Source values to parse MIB files, resolve cross-module imports, build the OID tree, and return a read-only mib.Mib containing the merged result.
Overview ¶
Most callers should stay at this package layer:
- Load runs the full parse, validate, and resolve pipeline.
- Source implementations such as Dir, File, Files, FS, and Multi control where modules are found.
- WithModules limits loading to selected modules and their transitive dependencies.
- WithSystemPaths discovers net-snmp and libsmi search paths.
Query Model ¶
The resolved query model lives in the github.com/gosnmp/gomib/mib package. Callers typically load through Load here, then query the resulting mib.Mib for modules, objects, types, notifications, table structure, and OID lookups.
Lower-Level Access ¶
For lower-level lexical access without full loading, use the github.com/gosnmp/gomib/token package.
Index ¶
- Constants
- Variables
- func DefaultExtensions() []string
- func DiscoverSystemPaths() []string
- func Load(ctx context.Context, opts ...LoadOption) (*mib.Mib, error)
- func ScanModuleNames(content []byte) []string
- type FindResult
- type LoadOption
- func WithDiagnosticConfig(cfg mib.DiagnosticConfig) LoadOption
- func WithLogger(logger *slog.Logger) LoadOption
- func WithModules(names ...string) LoadOption
- func WithResolverStrictness(level mib.ResolverStrictness) LoadOption
- func WithSource(src ...Source) LoadOption
- func WithSystemPaths() LoadOption
- type Source
- func Dir(root string, opts ...SourceOption) (Source, error)
- func DiscoverSystemSources() []Source
- func FS(name string, fsys fs.FS, opts ...SourceOption) Source
- func File(path string) (Source, error)
- func Files(paths ...string) (Source, error)
- func Multi(sources ...Source) Source
- func MustDir(root string, opts ...SourceOption) Source
- type SourceOption
Constants ¶
const LevelTrace = types.LevelTrace
LevelTrace is a custom log level more verbose than Debug. Use for per-item iteration logging (tokens, OID nodes, imports). Enable with: &slog.HandlerOptions{Level: slog.Level(-8)}
Variables ¶
var ErrDiagnosticThreshold = errors.New("diagnostic threshold exceeded")
ErrDiagnosticThreshold is returned when diagnostics exceed the configured FailAt severity. The Mib is still returned with all resolved data.
var ErrMissingModules = errors.New("requested modules not found")
ErrMissingModules is returned when WithModules names are not found in any source. The Mib is still returned with whatever modules could be loaded.
var ErrNoSources = errors.New("no MIB sources provided")
ErrNoSources is returned when Load is called with no sources.
Functions ¶
func DefaultExtensions ¶
func DefaultExtensions() []string
DefaultExtensions returns the file extensions recognized as MIB files. Empty string matches files with no extension (e.g., "IF-MIB").
func DiscoverSystemPaths ¶
func DiscoverSystemPaths() []string
DiscoverSystemPaths returns MIB directories from net-snmp and libsmi configuration, deduplicated and filtered to directories that exist.
func Load ¶
Load loads MIB modules from configured sources and resolves them.
Example:
m, err := gomib.Load(ctx,
gomib.WithSource(gomib.MustDir("/usr/share/snmp/mibs")),
gomib.WithModules("IF-MIB", "IP-MIB"),
)
m, err := gomib.Load(ctx, gomib.WithSystemPaths())
func ScanModuleNames ¶
ScanModuleNames extracts module names from raw MIB file bytes by finding identifiers that precede "DEFINITIONS ::=". This is a lightweight scan, not a full parse. ASN.1 comments are skipped so that commented-out module headers are not indexed. Returns nil if no module headers are found.
Types ¶
type FindResult ¶
type FindResult struct {
Content []byte
// Path is used in diagnostic messages to identify the source.
Path string
}
FindResult holds the content and location of a found MIB file.
type LoadOption ¶
type LoadOption func(*loadConfig)
LoadOption configures Load.
func WithDiagnosticConfig ¶
func WithDiagnosticConfig(cfg mib.DiagnosticConfig) LoadOption
WithDiagnosticConfig sets the diagnostic reporting and failure configuration.
DiagnosticConfig controls independent diagnostic policies:
- Reporting: the baseline severity retained in mib.Mib.Diagnostics.
- Overrides: the effective severity stored on matching diagnostics.
- Ignore: which non-fatal diagnostics are suppressed entirely.
- FailAt: which stored severity causes Load to return ErrDiagnosticThreshold.
This is separate from WithResolverStrictness, which controls how the resolver handles ambiguous or missing references. A permissive resolver still collects diagnostics, and those diagnostics are still subject to the FailAt threshold. Callers loading large vendor MIB sets typically want both permissive resolution and a relaxed FailAt (e.g. SeverityFatal).
func WithLogger ¶
func WithLogger(logger *slog.Logger) LoadOption
WithLogger sets the logger for debug/trace output. If not set, no logging occurs (zero overhead).
func WithModules ¶
func WithModules(names ...string) LoadOption
WithModules restricts loading to the named modules and their dependencies. Omit to load all modules from the configured sources.
func WithResolverStrictness ¶
func WithResolverStrictness(level mib.ResolverStrictness) LoadOption
WithResolverStrictness sets resolver fallback behavior for ambiguous or missing references.
This controls which heuristic fallbacks the resolver may use:
- mib.ResolverStrict: tier-1 only, no fallbacks. Unresolved references are left unresolved.
- mib.ResolverNormal: tier-1 + tier-2 constrained fallbacks (default).
- mib.ResolverPermissive: tier-1 + tier-2 + tier-3 global fallbacks. Best effort for vendor MIBs with spec violations.
This does not affect diagnostic failure policy. A permissive resolver still produces diagnostics that may exceed the mib.DiagnosticConfig.FailAt threshold. To also suppress failure on non-fatal diagnostics, configure WithDiagnosticConfig with FailAt set to mib.SeverityFatal.
func WithSource ¶
func WithSource(src ...Source) LoadOption
WithSource appends one or more MIB sources to the load configuration. Sources are searched in the order they are added.
func WithSystemPaths ¶
func WithSystemPaths() LoadOption
WithSystemPaths enables automatic discovery of MIB search paths from net-snmp and libsmi configuration (config files, env vars, defaults). Discovered paths are appended after any explicit source, serving as fallback. When source is nil and WithSystemPaths is set, system paths alone are sufficient.
type Source ¶
type Source interface {
// Find returns the MIB content for the named module,
// or fs.ErrNotExist if the module is not available.
Find(name string) (FindResult, error)
// ListModules returns all module names known to this source.
ListModules() ([]string, error)
}
Source provides access to MIB files for the loading pipeline. Implementations are passed to WithSource and searched in order during Load to locate module files by name. The standard implementations are Dir, FS, and Multi.
func Dir ¶
func Dir(root string, opts ...SourceOption) (Source, error)
Dir creates a Source that recursively indexes a directory tree. It walks the tree once at construction and builds a name->path index using content-derived module names (not filenames). First match wins for duplicate names.
func DiscoverSystemSources ¶
func DiscoverSystemSources() []Source
DiscoverSystemSources returns Sources for all discovered system MIB directories.
func FS ¶
func FS(name string, fsys fs.FS, opts ...SourceOption) Source
FS creates a Source backed by an fs.FS (e.g., embed.FS). The name is used as a prefix in diagnostic paths. The filesystem is lazily indexed on first use. Errors are deferred to the first Find or ListModules call.
func File ¶
File creates a Source from a single MIB file on disk. The module name is extracted from the file content by scanning for "DEFINITIONS ::=" headers, just like Dir does for directory trees. The caller does not need to know or provide the module name.
func Files ¶
Files creates a Source from multiple MIB files on disk. Module names are extracted from each file's content by scanning for "DEFINITIONS ::=" headers. When duplicate module names appear across files, the first file wins.
func Multi ¶
Multi combines multiple sources into one. Find() tries each source in order, returning the first match.
func MustDir ¶
func MustDir(root string, opts ...SourceOption) Source
MustDir is like Dir but panics on error.
type SourceOption ¶
type SourceOption func(*sourceConfig)
SourceOption modifies source behavior.
func WithExtensions ¶
func WithExtensions(exts ...string) SourceOption
WithExtensions overrides the default file extensions used to match MIB files. Extensions are normalized to lowercase with a leading dot (e.g. "mib" becomes ".mib"). An empty string matches files with no extension.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gomib
command
Command gomib is a CLI tool for loading, querying, and dumping MIB modules.
|
Command gomib is a CLI tool for loading, querying, and dumping MIB modules. |
|
gomib-fixturegen
command
gomib-fixturegen generates NormalizedNode JSON fixtures from gomib for cross-validation with mib-rs.
|
gomib-fixturegen generates NormalizedNode JSON fixtures from gomib for cross-validation with mib-rs. |
|
gomib-libsmi
command
Command gomib-libsmi compares gomib against libsmi for lexer/parser cross-validation.
|
Command gomib-libsmi compares gomib against libsmi for lexer/parser cross-validation. |
|
gomib-netsnmp
command
Command gomib-netsnmp compares gomib against net-snmp for cross-validation.
|
Command gomib-netsnmp compares gomib against net-snmp for cross-validation. |
|
internal/cliutil
Package cliutil provides shared CLI utilities for gomib command-line tools.
|
Package cliutil provides shared CLI utilities for gomib command-line tools. |
|
examples
|
|
|
basic
command
Load IF-MIB and print a module summary with selected objects.
|
Load IF-MIB and print a module summary with selected objects. |
|
diagnostics
command
Load MIBs at different strictness levels and show diagnostic output.
|
Load MIBs at different strictness levels and show diagnostic output. |
|
embed
command
Use embed.FS with gomib.FS() to load MIBs embedded in the binary.
|
Use embed.FS with gomib.FS() to load MIBs embedded in the binary. |
|
modules
command
Load embedded modules and inspect module metadata, imports, and visible symbols.
|
Load embedded modules and inspect module metadata, imports, and visible symbols. |
|
notifications
command
Load an embedded module and inspect notifications, groups, compliances, and capabilities.
|
Load an embedded module and inspect notifications, groups, compliances, and capabilities. |
|
query
command
Show different query patterns: by name, module-scoped, OID, and prefix matching.
|
Show different query patterns: by name, module-scoped, OID, and prefix matching. |
|
tables
command
Load several MIBs and demonstrate the table API: structure, indexes, columns, AUGMENTS relationships, index encoding, and navigation.
|
Load several MIBs and demonstrate the table API: structure, indexes, columns, AUGMENTS relationships, index encoding, and navigation. |
|
tokens
command
|
|
|
types
command
Show type chain walking, textual conventions, and effective constraints.
|
Show type chain walking, textual conventions, and effective constraints. |
|
internal
|
|
|
cst/lower
Package lower transforms CST nodes into module IR types.
|
Package lower transforms CST nodes into module IR types. |
|
cst/parser
Package parser provides a lossless CST parser for SMI MIB modules.
|
Package parser provides a lossless CST parser for SMI MIB modules. |
|
graph
Package graph provides dependency graph construction and analysis for MIB resolution.
|
Package graph provides dependency graph construction and analysis for MIB resolution. |
|
lexer
Package lexer provides tokenization for SMIv1/SMIv2 MIB source text.
|
Package lexer provides tokenization for SMIv1/SMIv2 MIB source text. |
|
model
Package model defines the resolved MIB data model types.
|
Package model defines the resolved MIB data model types. |
|
module
Package module provides a normalized representation of MIB modules.
|
Package module provides a normalized representation of MIB modules. |
|
testutil
Package testutil provides test assertion helpers.
|
Package testutil provides test assertion helpers. |
|
types
Package types provides internal types shared across gomib packages.
|
Package types provides internal types shared across gomib packages. |
|
Package mib re-exports the resolved MIB data model and resolver entry point.
|
Package mib re-exports the resolved MIB data model and resolver entry point. |
|
Package smiwrite emits resolved MIB models as canonical SMIv2 text.
|
Package smiwrite emits resolved MIB models as canonical SMIv2 text. |
|
Package syntax provides public access to the SMI MIB concrete syntax tree (CST), token types, and token kind constants.
|
Package syntax provides public access to the SMI MIB concrete syntax tree (CST), token types, and token kind constants. |