model_tool.pl

Overview

model_tool.pl is a command-line tool for developing, testing, and validating NMIS device models. It discovers SNMP capabilities, checks model structure, and validates models against schema definitions. Location: ~/admin/model_tool.pl Version: Part of NMIS 9 core

Command-Line Options

debug

integer

default:"0"

Set debugging level:

1: Basic debug info
2: Detailed debug with data structures
3: Verbose debug with schema details
4: Maximum verbosity

errors

boolean

default:"true"

Display model errors and warnings.

conf

string

Path to configuration directory (default: uses NMIS config).

Discovery Operations

Node Discovery

Discover SNMP MIBs supported by a node and identify applicable models.

model_tool.pl node=router1

node

string

required

NMIS node name to discover. Node must exist and be active.

file

string

Output file for detailed discovery results (TAB-delimited CSV format).

model

string

Name for auto-generated model. If specified, creates Model-<name>.nmis.

common_exclude

string

Regular expression to exclude Common-* models from auto-generated model.

Discovery Process:

Connects to node via SNMP
Tests all known SNMP OIDs from model files
Identifies supported MIBs and model sections
Reports which models and sections apply to the device
Optionally generates a new model file

Discovery Output Example:

node:           router1
sysDescr:       Cisco IOS Software, Version 15.2(4)M3
sysObjectID:    1.3.6.1.4.1.9.1.1045
nodeVendor:     Cisco Systems
nodeModel:      CiscoRouter

Common Things to Include:
  Adding common model Cisco-cef to model
  Adding common model Cisco-cbqos to model

System Health Sections:
'sections' => 'addressTable,cdp,bgpPeer,ospfNbr'

DISCOVERED: systemHealth Common-Cisco-cef.nmis systemHealth/sys/cefEntry 1.3.6.1.4.1.9.9.492.1.2.1 YES
DISCOVERED: systemHealth Common-Cisco-cdp.nmis systemHealth/sys/cdp 1.3.6.1.4.1.9.9.23.1.2.1 YES

Model Validation

Check Models

Validate model structure and syntax across all models.

model_tool.pl check=true

check

boolean

required

Enable model checking mode.

models_dir

string

default:"models-default"

Directory containing models to check: models or models-default.

Checks Performed:

Model file syntax and structure
RRD variable name length (max 19 characters)
Required sections and properties
Graph type definitions and files
SNMP OID validity
Model schema compliance
Reference integrity

Validation Output Example:

Processing Directory /usr/local/nmis9/models-default
Processed 87 NMIS Model files.

Checking graphtypes:
  Graph file found for graph type abits: Graph-abits.nmis
  Graph file found for graph type cpu: Graph-cpu.nmis
  Graph file found for graph type interface: Graph-interface.nmis

MODEL ERROR: RRD variable ifInOctetsLongName found longer than 19: Model-Example.nmis system/rrd/interface/snmp
MODEL ERROR: missing file for graph type custom_graph: Graph-custom_graph.nmis

15 model schema errors were found.

Schema Operations

Check Schema

Validate models against the schema definition.

model_tool.pl check=true schema=true

schema

boolean

default:"true"

Enable schema validation. Requires Model-Schema.nmis file.

Schema Files:

Primary: conf/Model-Schema.nmis
Fallback: conf-default/Model-Schema.nmis

Generate Schema

Create or update the model schema file based on existing models.

model_tool.pl make_schema=true models_dir=models-default

make_schema

boolean

required

Enable schema generation mode. Overwrites existing schema file.

Schema checking is automatically disabled during schema generation.

Advanced Operations

Check All Nodes

Load all active nodes and validate their model assignments.

model_tool.pl nodes=true

nodes

boolean

required

Enable nodes checking mode.

Purpose:

Verify all nodes can load their assigned models
Identify model compatibility issues
Detect missing or invalid model references

Model Structure Validation

RRD Variable Names

RRD (Round Robin Database) variable names must be ≤19 characters due to RRDtool limitations. Valid:

'ifInOctets' => {
  'oid' => 'ifInOctets',
  'option' => 'counter,0:U'
}

Invalid:

'ifInOctetsVeryLongName' => {  # ERROR: 22 characters
  'oid' => 'ifInOctets',
  'option' => 'counter,0:U'
}

Graph Type Validation

Each graphtype referenced in a model must have a corresponding Graph-*.nmis file. Model Section:

'rrd' => {
  'interface' => {
    'graphtype' => 'bits,abits,maxbits,util,autil'
  }
}

Required Files:

Graph-bits.nmis
Graph-abits.nmis
Graph-maxbits.nmis
Graph-util.nmis
Graph-autil.nmis

SNMP OID Resolution

OIDs must be resolvable via nmis_mibs.oid file or be numeric. Valid Formats:

'oid' => 'sysUpTime'              # Symbolic (must be in nmis_mibs.oid)
'oid' => '1.3.6.1.2.1.1.3'        # Numeric
'oid' => 'ifInOctets.1'           # Symbolic with index

Invalid:

'oid' => 'unknownMibObject'       # Not in nmis_mibs.oid

Output Files

Discovery Output File

Generated with file=<path> during discovery. TAB-delimited CSV format. Columns:

node: Node name
nodeModel: Assigned model
Type: system or systemHealth
File: Model filename
Path: Model section path
Supported: YES or NO
SNMP_Object: MIB object name
SNMP_OID: Numeric OID
OID_Used: OID queried
result: SNMP response value

Example:

node    nodeModel       Type            File                    Path                            Supported       SNMP_Object     SNMP_OID                result
router1 CiscoRouter     systemHealth    Common-Cisco-cef.nmis   systemHealth/sys/cefEntry      YES             cefFIBSummary   1.3.6.1.4.1.9.9.492.1   324
router1 CiscoRouter     system          Model-CiscoRouter.nmis  system/sys/sysDescr            YES             sysDescr        1.3.6.1.2.1.1.1        Cisco IOS...

Generated Model File

Created when model=<name> is specified during discovery. Location: <nmis_models>/Model-<name>.nmis Structure:

{
  'system' => {
    'nodeModel' => 'MyNewModel',
    'nodeModelComment' => 'Auto Generated Model by model_tool.pl',
    'rrd' => { ... },
    'sys' => { ... }
  },
  'systemHealth' => {
    'sections' => 'addressTable,cdp,bgpPeer',
    'rrd' => { ... },
    'sys' => { ... }
  },
  '-common-' => {
    'class' => {
      'Cisco-cef' => { 'common-model' => 'Cisco-cef' },
      'Cisco-cbqos' => { 'common-model' => 'Cisco-cbqos' }
    }
  }
}

Configuration Files

Model Schema

File: conf/Model-Schema.nmis or conf-default/Model-Schema.nmis Defines valid model structure, keywords, and their relationships. Structure:

{
  'reserved' => [ 'system', 'systemHealth', 'interface', ... ],
  'keywords' => {
    'oid' => {
      'name' => 'oid',
      'parents' => [ 'snmp', 'alert', 'threshold' ],
      'locations' => [ 'system/sys/...', ... ],
      'refs' => [ 'SCALAR' ],
      'types' => [ 'string', 'dotted-decimal' ]
    },
    ...
  }
}

MIB OID Mapping

File: <mib_root>/nmis_mibs.oid Maps symbolic MIB names to numeric OIDs. Format:

"sysDescr" "1.3.6.1.2.1.1.1"
"ifInOctets" "1.3.6.1.2.1.2.2.1.10"
"cefFIBSummary" "1.3.6.1.4.1.9.9.492.1.2.1"

Common Use Cases

Developing a New Model

model_tool.pl node=new-device debug=2 \
  file=/tmp/new-device-discovery.txt

Troubleshooting Model Issues

model_tool.pl check=true debug=2

Creating Common Models

model_tool.pl node=device1 debug=2
model_tool.pl node=device2 debug=2
model_tool.pl node=device3 debug=2

Maintaining Model Quality

#!/bin/bash
# Daily model validation script
cd /usr/local/nmis9
model_tool.pl check=true errors=true > /tmp/model-check.log 2>&1

if grep -q "ERROR" /tmp/model-check.log; then
  echo "Model errors found - review required"
  mail -s "NMIS Model Errors" [email protected] < /tmp/model-check.log
fi

Error Types

MODEL ERROR

Structural or syntax errors in model files. Examples:

MODEL ERROR: RRD variable ifInOctetsLongName found longer than 19
MODEL ERROR: missing file for graph type custom_graph
MODEL ERROR: Could not load Model-Broken.nmis
MODEL ERROR: with Model OID ... invalid OID format

SCHEMA ERROR

Schema validation failures. Examples:

SCHEMA ERROR: Keyword custom_field incorrect path: Model-Custom.nmis system/sys/special
SCHEMA ERROR: Keyword indexed incorrect parent snmp

Exit Codes

0: Success
1: Error (missing node, invalid arguments)
-1: Invalid directory

Environment Variables

None required. Uses NMIS configuration.

Limitations

Discovery requires active SNMP connectivity
Large SNMP tables may timeout (adjust max_repetitions in node config)
Schema validation requires up-to-date schema file
Discovery is limited to ~10,000 MIB tests per run
RRD variable names limited to 19 characters (RRDtool restriction)

Tips and Best Practices

Model Development

Always discover before creating: Run discovery to understand device capabilities
Use common models: Extract shared functionality into Common-* models
Validate early and often: Check models after each significant change
Test with real devices: Discovery against actual hardware reveals issues
Follow naming conventions: Keep RRD variable names short and descriptive

Discovery Optimization

Start with basic discovery: Use debug=1 initially
Enable detailed output: Use debug=2 to see SNMP responses
Save discovery results: Always use file= to preserve output
Use common_exclude wisely: Exclude sections you know aren’t needed

Validation Workflow

Local validation first: Check models locally before deploying
Schema compliance: Enable schema checking for strict validation
Test node loading: Use nodes=true to verify all nodes load correctly
Review graph types: Ensure all graph files exist

Core Libraries

CLI Commands

​Overview

​Command-Line Options

​Discovery Operations

​Node Discovery

​Model Validation

​Check Models

​Schema Operations

​Check Schema

​Generate Schema

​Advanced Operations

​Check All Nodes

​Model Structure Validation

​RRD Variable Names

​Graph Type Validation

​SNMP OID Resolution

​Output Files

​Discovery Output File

​Generated Model File

​Configuration Files

​Model Schema

​MIB OID Mapping

​Common Use Cases

​Developing a New Model

​Troubleshooting Model Issues

​Creating Common Models

​Maintaining Model Quality

​Error Types

​MODEL ERROR

​SCHEMA ERROR

​Exit Codes

​Environment Variables

​Limitations

​Tips and Best Practices

​Model Development

​Discovery Optimization

​Validation Workflow

​See Also

Build docs developers (and LLMs) love

Overview

Command-Line Options

Discovery Operations

Node Discovery

Model Validation

Check Models

Schema Operations

Check Schema

Generate Schema

Advanced Operations

Check All Nodes

Model Structure Validation

RRD Variable Names

Graph Type Validation

SNMP OID Resolution

Output Files

Discovery Output File

Generated Model File

Configuration Files

Model Schema

MIB OID Mapping

Common Use Cases

Developing a New Model

Troubleshooting Model Issues

Creating Common Models

Maintaining Model Quality

Error Types

MODEL ERROR

SCHEMA ERROR

Exit Codes

Environment Variables

Limitations

Tips and Best Practices

Model Development

Discovery Optimization

Validation Workflow

See Also