NXShell

NXShell is a command-line tool for scripting NetXMS server operations using Python (Jython). It provides a Python environment with access to the NetXMS Java client library, enabling automation of administrative tasks, bulk operations, and custom integrations.

Overview

NXShell is built on Jython (Python running on the JVM) and provides access to the NetXMS Java client API — commonly used org.netxms.* packages are pre-imported; anything else can be imported explicitly. This makes it suitable for:

  • Bulk operations on objects (rename, reconfigure, delete)

  • Automated report generation and data export

  • Custom monitoring checks and data manipulation

  • Integration scripts that connect NetXMS with other systems

  • One-time migration and cleanup tasks

Installation

NXShell is a client-side tool distributed with the NetXMS client tools. It connects to the server over the network like any other management client — it does not need to run on the server host.

Prerequisites

  • Java Runtime Environment (JRE) 11 or later

  • The NetXMS client libraries (netxms-base and netxms-client jars, bundled with the tool)

NXShell embeds Jython 2.7, which implements Python 2 — use print statements and Python 2 string formatting; Python 3 syntax such as f-strings will not work.

Running NXShell

Start an interactive session:

nxshell -H server_address -u admin -P password

Run a script file:

nxshell -H server_address -u admin -P password script.py
Passing passwords on the command line exposes them in shell history and process listings. For non-interactive use (scripts), prefer token authentication (-t option). For interactive use, omit -P to be prompted for the password securely.

For command-line options, Java properties, and API class reference, see NXShell Reference.

Practical Examples

Rename All Nodes in a Container

container = session.findObjectByName("Legacy Servers")
for child in container.getAllChildren(-1):
    if child.getObjectClass() == 2:  # Node
        oldName = child.getObjectName()
        newName = oldName.replace("old-", "new-")
        if oldName != newName:
            md = NXCObjectModificationData(child.getObjectId())
            md.setName(newName)
            session.modifyObject(md)
            print "Renamed: %s -> %s" % (oldName, newName)

Export DCI Data to CSV

import csv
from java.util import Calendar
from org.netxms.client.constants import HistoricalDataType

node = session.findObjectByName("server01")
dciId = 100

cal = Calendar.getInstance()
endTime = cal.getTime()
cal.add(Calendar.DAY_OF_MONTH, -30)
startTime = cal.getTime()

data = session.getCollectedData(node.getObjectId(), dciId, startTime, endTime, 0, HistoricalDataType.PROCESSED)
rows = data.getValues()

with open("/tmp/dci_export.csv", "wb") as f:
    writer = csv.writer(f)
    writer.writerow(["Timestamp", "Value"])
    for row in rows:
        writer.writerow([str(row.getTimestamp()), row.getValueAsString()])

print "Exported %d rows to /tmp/dci_export.csv" % len(rows)

Bulk Set Custom Attributes from CSV

import csv
from java.util import HashMap
from org.netxms.client.objects.configs import CustomAttribute

with open("/tmp/node_attributes.csv", "rb") as f:
    reader = csv.DictReader(f)
    for row in reader:
        node = session.findObjectByName(row["node_name"])
        if node is not None:
            attrs = HashMap(node.getCustomAttributes())
            attrs.put("location", CustomAttribute(row["location"], 0, 0))
            attrs.put("owner", CustomAttribute(row["owner"], 0, 0))
            md = NXCObjectModificationData(node.getObjectId())
            md.setCustomAttributes(attrs)
            session.modifyObject(md)
            print "Updated: %s" % row["node_name"]
        else:
            print "Node not found: %s" % row["node_name"]

Delete Old Alarms

from java.util import Calendar

cal = Calendar.getInstance()
cal.add(Calendar.DAY_OF_MONTH, -90)
cutoff = cal.getTime()

alarms = session.getAlarms()
count = 0
for alarm in alarms.values():
    if alarm.getLastChangeTime().before(cutoff):
        session.terminateAlarm(alarm.getId())
        count += 1

print "Terminated %d alarms older than 90 days" % count

Tips

  • Use dir(object) to explore available methods in interactive mode

  • NXShell scripts are Python 2 (Jython) — you can use loops, conditionals, file I/O, and standard library modules

  • For large bulk operations, add progress output and consider batching with small delays to avoid overloading the server

  • Store credentials in environment variables rather than hardcoding them in scripts

  • Use try/except blocks for error handling in production scripts

Next Steps