Table of Contents

Table of Contents

NMIS provides a number of different methods for managing your nodes, both GUI-based and commandline-oriented. This document describes the commandline tools present in versions 8.5.4 and newer.

Bulk Import and Export

For importing lots of nodes in one go from a CSV file, NMIS has been providing admin/import_nodes.pl for a long time. There is also a sibling admin/export_nodes.pl tool, and both are documented on the Bulk Import page. The main benefit of these tools is utmost simplicity, but at the cost of some flexibility: import_nodes does not make all common node properties controllable or accessible.

Node administration with `node_admin.pl`

Version 8.5.4G brings in a new, more fine-grained and capable tool: admin/node_admin.pl. It's scriptable and pipelineable, and can perform all node-related operations: creation, updating, renaming, exporting and deletion of nodes.

Basic Operation

Related Documentation

Import nodes to NMIS9 from NMIS8

To import nodes from NMIS8 to NMIS9 copy /path/to/nmis8/conf/Nodes.nmis to /tmp/ on NMIS9 installation then:

Code Block
/usr/local/nmis9/admin/node_admin.pl act=import_bulk nodes="/tmp/Nodes.nmis"

Caveats: you can not import a node to a server if there is already a node existing with that name, you should rename the node before importing.

Bulk Import and Export

For importing lots of nodes in one go from a CSV file, NMIS has been providing admin/import_nodes.pl for a long time. There is also a sibling admin/export_nodes.pl tool, and both are documented on the Bulk Import page. The main benefit of these tools is utmost simplicity, but at the cost of some flexibility: import_nodes does not make all common node properties controllable or accessible.

Node administration with `node_admin.pl`

Version 8.5.4G brings in a new, more fine-grained and capable tool: admin/node_admin.pl. It's scriptable and pipelineable, and can perform all node-related operations: creation, updating, renaming, exporting and deletion of nodes.

Basic Operation

Run the tool with no options or Run the tool with no options or -? or -h and it'll display a simple help page:

...

You can also use file=- to indicate that STDOUT should be used for export or STDIN be used for update/creation. The act=update operation doesn't create new nodes, and it replaces the whole set of node configuration settings with your new configuration input. So, if a property is not set, it will disappear. For change only one property, the operation "set" is more accurate.

Creation of NodesCreation of Nodes

The creation of nodes requires you to use a template (shown below) instead of using a command line argument; this . This is because NMIS requires numerous node properties to be set up correctly making it easy to miss some when operating via command line arguments. Node creation is triggered by the argument act=create, which behaves mostly like act=update, except that it doesn't touch existing nodes. To help you with starting a node configuration document from scratch (or in a scripted fashion), there is another command, act=mktemplate, which prints a blank but documented template which you can save and fill in. If you add placeholder=1 to the command line, then node_admin fills the template with easily matchable replacement placeholders, like so:

...

Code Block
./node_admin.pl act=delete node=ripnode confirm=YES deletedata=1 Successfully deleted ripnode

Node Properties

NMIS uses a subset of the node properties of the commercial Opmantek tools. node_admin.pl act=mktemplate includes a very brief listing of the most essential ones from NMIS' perspective, and the Common Node Properties wiki page describes most of the important ones in greater detail.

NMIS9 Enhancements

The node admin tool in NMIS9 brings some enhancements.

The node_admin tool now supports more complete snapshotting of nodes (with act=dump), which optionally includes the node's RRD files, events and other historic records.
When importing a thusly dumped node with act=import it is now possible to have all identifiers localised to the current system (with localise_ids=true ); this causes the imported node to be 'adopted' by and become active on the current NMIS system immediately.
This mechanism allows a node to be moved completely between NMIS systems, without losing any of the node's history.

Backup, Migrate or just play with a Node

Simple node export and import are described above, however, with NMIS9 you can backup a node and perform node migrations using the node_admin.pl tool, the functions to do this are dump and restore.

Dump (or Backup) a Node

Using the node_admin.pl tool you can dump a node including all database records and RRD files into a ZIP file.

Code Block
/usr/local/nmis9/admin/node_admin.pl node=NODENAME act=dump everything=1 file=/tmp/NODENAME-dump.zip

This file would represent a backup of that node at this time. The file can then be used on another server to restore or could be used to restore the node on the same server.

Restoring a Node

To restore a node to the same poller you would not need to localise_ids option, if you wanted to copy/migrate the node to another server you would need to localise the ids so that the poller thinks it the node belongs to it.

Code Block
/usr/local/nmis9/admin/node_admin.pl act=restore file=NODENAME-dump.zip localise_ids=1

Caveats: you can not restore a node to a server if there is already a node existing with that name, you should rename the node before dumping. This would include if the server was acting as a master and receiving the node from a remote poller.

Copy a Node

To make a duplicate node and start polling it, export the node, edit the json and import it, e.g.

Code Block
/usr/local/nmis9/admin/node_admin.pl act=export node=NODENAME file=NODENAME.json

Edit NODENAME.json, change the display_name and name in the file and then import it

Code Block
/usr/local/nmis9/admin/node_admin.pl act=import file=NODENAME.json

The node will be created with the name used in the name field.

NMIS9 Basic Operation

Run the tool with no options or -? or -h and it'll display a simple help page:

...

A backup will be created by default from NMIS 9.1.1 based in the configuration options:

Code Block
backup_node_on_delete => true by default. keeprrds_on_delete_node => false by default. node_dumps_dir => Delete backup dir, by default in var/node_dumps purge_node_dumps_after => 30 by default

Background Operations

From NMIS 9.1.1, the basic operations can be run in the background with new jobs for the scheduler. It is so simple as adding schedule=1 for create, update, remove and set operations.

As an example:

Code Block
./node_admin.pl file=node1.json act=create schedule=1 Job 5f6492872b1813263276fda1 created for type create_nodes and 1 nodes.

update and create operations were improved allowing an array of nodes in the json file.

Remote Nodes Operations

From NMIS 9.1.1, NMIS accepts operations with remote nodes. It is so simple as adding server=server_name|server_id for create, update, remove and set operations.

As an example:

Code Block
./node_admin.pl node=asgard1234 confirm=YES act=delete server=285b0b31-dfa5-4a46-a55b-a66384727dc8 Successfully marked for delete node (2).

opHA will process later these operations and will update the changes in the remote nodes.

Please note, for delete operation, the node will be marked for delete, but won't be removed until opHA will process that node.

Poller Server

From NMIS 9.1.1, if a node is marked as as Poller, the actions in the node_admin tool will be limited to list/show/dump/restore.

Node Properties

NMIS uses a subset of the node properties of the commercial Opmantek tools. node_admin.pl act=mktemplate includes a very brief listing of the most essential ones from NMIS' perspective, and the Common Node Properties wiki page describes most of the important ones in greater detail.

NMIS9 Enhancements

The node admin tool in NMIS9 brings some enhancements.

NMIS9 example of json format for a node

Code Block

# "/usr/local/nmis9/admin/node_admin.pl" act=export node=localhost
{
   "activated" : {
      "NMIS" : 1,
      "opConfig" : 1,
      "opEvents" : 1
   },
   "addresses" : [
      {
         "address" : "127.0.0.1"
      }
   ],
   "aliases" : [],
   "configuration" : {
      "active" : 1,
      "authkey" : "",
      "authpassword" : "",
      "authprotocol" : "md5",
      "businessService" : "",
      "calls" : 0,
      "cbqos" : "none",
      "collect" : 1,
      "community" : "nmisGig8",
      "context" : "",
      "customer" : "Opmantek",
      "depend" : [
         "N/A"
      ],
      "display_name" : "",
      "group" : "NMIS9",
      "host" : "127.0.0.1",
      "host_backup" : "",
      "location" : "Amsterdam",
      "max_msg_size" : 1472,
      "max_repetitions" : 0,
      "model" : "automatic",
      "netType" : "lan",
      "node_context_name" : "",
      "node_context_url" : "",
      "notes" : "",
      "ping" : 1,
      "polling_policy" : "default",
      "port" : 161,
      "privkey" : "",
      "privpassword" : "",
      "privprotocol" : "des",
      "remote_connection_name" : "",
      "remote_connection_url" : "",
      "roleType" : "distribution",
      "serviceStatus" : "Development",
      "services" : [
         "SNMP_Daemon",
         "http_server",
         "port22",
         "port25",
         "port80",
         "opmantek.pl",
         "mongo_daemon",
         "omkd check",
         "opchartsd",
         "opconfigd",
         "opeventsd",
         "nmis cgi",
         "nmis9d",
         "check_disk_write"
      ],
      "threshold" : 1,
      "timezone" : 0,
      "username" : "",
      "version" : "snmpv2c",
      "webserver" : 1,
      "wmipassword" : "",
      "wmiusername" : ""
   },
   "lastupdate" : 1592715346,
   "name" : "localhost",
   "overrides" : {}
}

Backup, Migrate or just play with a Node

Simple node export and import are described above, however, with NMIS9 you can backup a node and perform node migrations using the node_admin.pl tool, the functions to do this are dump and restore.

Dump (or Backup) a Node

Using the node_admin.pl tool you can dump a node including all database records and RRD files into a ZIP file.

Code Block
/usr/local/nmis9/admin/node_admin.pl node=NODENAME act=dump everything=1 file=/tmp/NODENAME-dump.zip

This file would represent a backup of that node at this time. The file can then be used on another server to restore or could be used to restore the node on the same server.

Restoring a Node

To restore a node to the same poller you would not need to use the localise_ids option. If you wanted to copy/migrate the node to another server you would need to localise the ids so that the poller thinks it the node belongs to it.

When the below command is executed, you will overwrite the previous cluster_id with the cluster_id of the NMIS server you are migrating/copying the node to.

Code Block
/usr/local/nmis9/admin/node_admin.pl act=restore file=NODENAME-dump.zip localise_ids=true

Caveats: you can not restore a node to a server if there is already a node existing with that name, you should rename the node before dumping. This would include if the server was acting as a Primary and receiving the node from a remote poller.

Copy a Node

To make a duplicate node and start polling it, export the node, edit the json and import it, e.g.

Code Block
/usr/local/nmis9/admin/node_admin.pl act=export node=NODENAME file=NODENAME.json

Edit NODENAME.json, change the display_name and name in the file and then import it

Code Block
/usr/local/nmis9/admin/node_admin.pl act=import file=NODENAME.json

The node will be created with the name used in the name field.

NMIS9 Basic Operation

Run the tool with no options or -? or -h and it'll display a simple help page:

Code Block

Usage: node_admin.pl act=[action to take] [extras...]

	node_admin.pl act={list|list_uuid} [node=X] [group=Y]
	node_admin.pl act=show node=nodeX
	node_admin.pl act={create|update} file=someFile.json
	node_admin.pl act=export [format=nodes] [file=path] {node=nodeX|group=groupY} [keep_ids=0/1]
	node_admin.pl act=import file=somefile.json
	node_admin.pl act=import_bulk {nodes=filepath|nodeconf=dirpath}
	node_admin.pl act=delete {node=nodeX|group=groupY}
	node_admin.pl act=dump {node=nodeX|uuid=uuidY} file=path [everything=0/1]
	node_admin.pl act=restore file=path [localise_ids=0/1]

	node_admin.pl act=set node=nodeX entry.X=Y...
	node_admin.pl act=mktemplate [placeholder=1/0]
	node_admin.pl act=rename old=nodeX new=nodeY [entry.A=B...]

mktemplate: prints blank template for node creation,
 optionally with __REPLACE_XX__ placeholder

create: requires file=NewNodeDef.json
update: updates existing node from file=someFile.json

export: exports to file=someFile (or STDOUT if no file given),
 either json or as Nodes.nmis if format=nodes is given
 uuid and cluster_id are NOT exported unless keep_ids is 1.

delete: only deletes if confirm=yes (in uppercase) is given,
 if deletedata=true (default) then RRD files for a node are
 also deleted.

show: prints a node's properties in the same format as set
 with option quoted=true, show adds double-quotes where needed
set: adjust one or more node properties

restore: restores a previously dumped node's data. if 
 localise_ids=true (default: false), then the cluster id is rewritten
 to match the local nmis installation.

extras: debug={1..9,verbose} sets debugging verbosity
extras: info=1 sets general verbosity

FAQ

Cluster and server mismatch!

When creating/updating a node, there are a couple of reasons this message can appear:

Server parameter is specified: The parameter is used if we want to send the node to a remote peer, and is optional. If the server does not exist (This is not the local server or this is not from any of the opHA peers), we will see this message. Also, the cluster_id needs to be specified in the json node data, and match with the server_id from the poller. Please notice this action is not online, please check the opHA guide for further details.
The json from the node includes a cluster_id which does not exist. Doesn't exist has the same meaning as above. If the cluster_id is not specified in the node data, nmis9 will import the node with the local cluster_id, which means, we can also omit that parameter.

Status

colour	Yellow
title	TIP

To create a json template for a node, we can use ./node_admin.pl act=mktemplate placeholder=1

Invalid server!

When creating/updating a node, nmis9 does not have this node registered.

This can be fixed in opHA, editing the peer.

Space shortcuts

Page tree

Versions Compared

Old Version 16

New Version Current

Key

Bulk Import and Export

Node administration with `node_admin.pl`

Basic Operation

Import nodes to NMIS9 from NMIS8

Bulk Import and Export

Node administration with `node_admin.pl`

Basic Operation

Creation of NodesCreation of Nodes

Node Properties

NMIS9 Enhancements

Backup, Migrate or just play with a Node

Dump (or Backup) a Node

Restoring a Node

Copy a Node

NMIS9 Basic Operation

Background Operations

Remote Nodes Operations

Poller Server

Node Properties

NMIS9 Enhancements

NMIS9 example of json format for a node

Backup, Migrate or just play with a Node

Dump (or Backup) a Node

Restoring a Node

Copy a Node

NMIS9 Basic Operation

FAQ

Cluster and server mismatch!

Invalid server!

Related Topics

Opmantek Node Administration with opnode_admin

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 16

New Version Current

Key

Bulk Import and Export

Node administration with node_admin.pl

Basic Operation

Import nodes to NMIS9 from NMIS8

Bulk Import and Export

Node administration with node_admin.pl

Basic Operation

Creation of NodesCreation of Nodes

Node Properties

NMIS9 Enhancements

Backup, Migrate or just play with a Node

Dump (or Backup) a Node

Restoring a Node

Copy a Node

NMIS9 Basic Operation

Background Operations

Remote Nodes Operations

Poller Server

Node Properties

NMIS9 Enhancements

NMIS9 example of json format for a node

Backup, Migrate or just play with a Node

Dump (or Backup) a Node

Restoring a Node

Copy a Node

NMIS9 Basic Operation

FAQ

Cluster and server mismatch!

Invalid server!

Related Topics

Opmantek Node Administration with opnode_admin

Node administration with `node_admin.pl`

Node administration with `node_admin.pl`