node_admin.pl

Overview

node_admin.pl is the command-line tool for managing NMIS nodes - creating, updating, deleting, importing, and exporting node configurations. Location: ~/admin/node_admin.pl Version: 9.5.1

Command-Line Options

--debug

integer

default:"0"

Set debugging level (0-9).

--help

flag

Display help information and exit.

--quiet

flag

Suppress non-essential output.

--skip_ha_warnings

flag

Suppress warnings when server role is not Standalone.

--usage

flag

Display usage information and exit.

--version

flag

Display version information and exit.

Server Role Restrictions

Most operations are restricted on POLLER servers. Only dump, list, restore, and show actions are available on poller nodes.

The tool displays a warning when run on non-Standalone servers (PRIMARY/POLLER). Use skip_ha_warnings=1 to suppress.

Node Management Operations

create

Create a new node from a JSON definition file.

node_admin.pl act=create file=/path/to/node.json

file

string

required

Path to JSON file containing node definition.

server

string

Target server name or cluster_id for remote poller.

schedule

boolean

default:"false"

Schedule the operation instead of executing immediately.

priority

number

default:"0"

Job priority (0-1) when scheduled.

verbosity

string

Logging level: debug, info, warn, error, or fatal.

update

Update an existing node from a JSON file. If no UUID is present, creates a new node.

node_admin.pl act=update file=/path/to/node.json

file

string

required

Path to JSON file containing node configuration.

If a property is not set in the file, it will be removed from the node. Use act=set to update only specific properties.

delete

Delete one or more nodes.

node_admin.pl act=delete node=router1 confirm=YES

node

string

Node name(s) - comma-separated for multiple.

uuid

string

Node UUID(s) - comma-separated for multiple.

group

string

Node group(s) - comma-separated for multiple.

confirm

string

required

Must be YES (uppercase) to confirm deletion.

deletedata

boolean

default:"true"

Also delete RRD files for the node.

Deletion is permanent and cannot be undone. Always ensure you have backups before deleting nodes.

set

Update specific properties for one or more nodes.

node_admin.pl act=set node=router1 entry.configuration.collect=true

entry.*

varies

required

Properties to set. Format: entry.<section>.<property>=<value>Common sections:

entry.configuration.* - Node configuration
entry.overrides.* - Node overrides
entry.activated.* - Activation status
entry.addresses.* - IP addresses (array)
entry.aliases.* - Node aliases (array)
entry.comments.* - Comments (array)
entry.unknown.* - Custom properties

Use entry.configuration.active=<true|false> which is translated to entry.activated.NMIS for backwards compatibility.

unset

Remove specific properties from one or more nodes.

node_admin.pl act=unset node=router1 entry.configuration.community=

Cannot unset entry.name or entry.cluster_id - these are required properties.

rename

Rename a node.

node_admin.pl act=rename old=router1 new=core-router1

old

string

Current node name (use old or uuid).

uuid

string

Node UUID (use old or uuid).

new

string

required

New node name.

Data Import/Export

export

Export node configurations to a file.

node_admin.pl act=export node=router1 file=/tmp/router1.json

node

string

Node name to export.

uuid

string

Node UUID to export.

group

string

Export all nodes in group.

file

string

Output file path. Use - for STDOUT. If omitted, outputs to STDOUT.

format

string

Export format: nodes for NMIS8 legacy format (default is NMIS9 JSON).

keep_ids

boolean

default:"false"

Include uuid and cluster_id in export (normally removed).

overwrite

boolean

default:"false"

Overwrite existing file.

import

Import node configurations from a JSON file.

node_admin.pl act=import file=/path/to/node.json

file

string

required

Path to JSON file (single node object or array of nodes).

Import will create new nodes or update existing ones based on UUID. If a node with the same name exists but no UUID is provided, import will fail.

import_bulk

Bulk import from NMIS8 format files.

node_admin.pl act=import_bulk nodes=/path/to/Nodes.nmis

nodes

string

Path to nodes file (NMIS8 format or JSON array).

nodeconf

string

Path to directory containing node override JSON files.

nmis9_format

boolean

default:"false"

Nodes file is in NMIS9 JSON format.

bulk_number

integer

Number of nodes to process before pausing.

delay

integer

default:"300"

Seconds to pause after processing bulk_number nodes.

dump

Create a complete backup dump of a node (config + data).

node_admin.pl act=dump node=router1 file=/backup/router1-dump.json

node

string

Node name (use node or uuid).

uuid

string

Node UUID (use node or uuid).

file

string

required

Path to dump file.

everything

boolean

default:"false"

Include all historic events, unlimited opstatus data, and RRD files.Default limits:

Historic events: excluded
Opstatus records: 1000 most recent
RRD data: excluded

restore

Restore a node from a dump file.

node_admin.pl act=restore file=/backup/router1-dump.json

file

string

required

Path to dump file created by act=dump.

localise_ids

boolean

default:"false"

Rewrite cluster_id to match local NMIS installation.

Query Operations

show

Display node properties.

node_admin.pl act=show node=router1

node

string

Node name (use node or uuid).

uuid

string

Node UUID (use node or uuid).

quoted

boolean

default:"false"

Add double-quotes around values with special characters.

interfaces

boolean

default:"false"

Display interface information.

inventory

boolean

default:"false"

Display all inventory data.

catchall

boolean

default:"false"

Display only catchall inventory data.

Output Format:

entry.configuration.host=192.168.1.1
entry.configuration.community=public
entry.configuration.group=core
entry.activated.NMIS=true

list (or list_uuid)

List nodes in the system.

node_admin.pl act=list

node

string

Filter by node name(s) - comma-separated.

uuid

string

Filter by UUID(s) - comma-separated.

group

string

Filter by group(s) - comma-separated.

wantuuid

boolean

default:"false"

Include UUID in output.

wantgroup

boolean

default:"false"

Include group in output.

wantpoller

boolean

default:"false"

Include poller/cluster_id in output.

wantstatus

boolean

default:"false"

Include active/collect status.

format

string

Output format: json (default is text table).

file

string

Write output to file (use - for STDOUT).

overwrite

boolean

default:"false"

Overwrite existing file.

Template Operations

mktemplate

Generate a blank node template.

node_admin.pl act=mktemplate

placeholder

boolean

default:"false"

Use __REPLACE_XX__ placeholders instead of empty values.

Output Example:

{
  "name": "__REPLACE_NAME__",
  "configuration": {
    "host": "__REPLACE_HOST__",
    "group": "__REPLACE_GROUP__",
    "community": "public",
    "active": true,
    "collect": true
  }
}

Maintenance Operations

clean-node-events

Clean up events for a specific node.

node_admin.pl act=clean-node-events node=router1

move-nmis8-rrd-files

Migrate RRD files from NMIS8 structure to NMIS9.

node_admin.pl act=move-nmis8-rrd-files node=router1

node

string

required

Node name or ALL for all nodes.

remove_old

boolean

default:"false"

Delete old RRD files after successful move.

force

boolean

default:"false"

Force move even if files exist at destination.

validate-node-inventory

Validate and optionally fix node inventory data.

node_admin.pl act=validate-node-inventory dryrun=true

concept

string

Validate specific inventory concept (e.g., interface, device).

dryrun

boolean

default:"false"

Show what would be changed without making changes.

make_historic

boolean

default:"false"

Mark invalid inventory as historic.

JSON Output Format

Node Export Structure (NMIS9)

{
  "name": "router1",
  "cluster_id": "nmis-primary",
  "uuid": "abc-123-def-456-789",
  "configuration": {
    "host": "192.168.1.1",
    "group": "core",
    "community": "public",
    "version": "snmpv2c",
    "port": 161,
    "active": true,
    "collect": true,
    "model": "automatic",
    "roleType": "core",
    "netType": "wan",
    "polling_policy": "default"
  },
  "activated": {
    "NMIS": true
  },
  "overrides": {
    "model": "CiscoRouter"
  },
  "addresses": {
    "192.168.1.1": {
      "interface": "Loopback0",
      "description": "Management"
    }
  },
  "aliases": [
    "core-rtr-1",
    "primary-gateway"
  ],
  "comments": [
    ["2024-12-01", "admin", "Initial configuration"],
    ["2024-12-15", "admin", "Updated SNMP community"]
  ]
}

List Output (JSON)

[
  {
    "name": "router1",
    "uuid": "abc-123-def",
    "cluster_id": "local",
    "group": "core",
    "active": "Yes",
    "collect": "Yes"
  },
  {
    "name": "switch1",
    "uuid": "def-456-ghi",
    "cluster_id": "local",
    "group": "access",
    "active": "Yes",
    "collect": "No"
  }
]

Exit Codes

0: Success
1: Error or no matching nodes found
2: Help displayed

Examples

Complete Node Lifecycle

node_admin.pl act=mktemplate placeholder=true > /tmp/new-node.json
# Edit /tmp/new-node.json with actual values

Bulk Operations

node_admin.pl act=export file=/backup/all-nodes.json

Migration Scenario

node_admin.pl act=export format=nodes file=/tmp/nmis8-nodes.nmis

Core Libraries

CLI Commands

node_admin.pl

Overview

Command-Line Options

Server Role Restrictions

Node Management Operations

create

update

delete

set

unset

rename

Data Import/Export

export

import

import_bulk

dump

restore

Query Operations

show

list (or list_uuid)

Template Operations

mktemplate

Maintenance Operations

clean-node-events

move-nmis8-rrd-files

validate-node-inventory

JSON Output Format

Node Export Structure (NMIS9)

List Output (JSON)

Exit Codes

Examples

Complete Node Lifecycle

Bulk Operations

Migration Scenario

See Also

Build docs developers (and LLMs) love

Core Libraries

CLI Commands

​Overview

​Command-Line Options

​Server Role Restrictions

​Node Management Operations

​create

​update

​delete

​set

​unset

​rename

​Data Import/Export

​export

​import

​import_bulk

​dump

​restore

​Query Operations

​show

​list (or list_uuid)

​Template Operations

​mktemplate

​Maintenance Operations

​clean-node-events

​move-nmis8-rrd-files

​validate-node-inventory

​JSON Output Format

​Node Export Structure (NMIS9)

​List Output (JSON)

​Exit Codes

​Examples

​Complete Node Lifecycle

​Bulk Operations

​Migration Scenario

​See Also

Build docs developers (and LLMs) love

Overview

Command-Line Options

Server Role Restrictions

Node Management Operations

create

update

delete

set

unset

rename

Data Import/Export

export

import

import_bulk

dump

restore

Query Operations

show

list (or list_uuid)

Template Operations

mktemplate

Maintenance Operations

clean-node-events

move-nmis8-rrd-files

validate-node-inventory

JSON Output Format

Node Export Structure (NMIS9)

List Output (JSON)

Exit Codes

Examples

Complete Node Lifecycle

Bulk Operations

Migration Scenario

See Also