NXShell Reference

This page provides a reference for NXShell command-line options, Java properties, and API classes.

For installation, usage examples, and practical scripts, see NXShell.

Command-Line Options

nxshell [<options>] [<script>]

Without a script file, an interactive Python console is started.

Option Description

-H, --host

NetXMS server host name or IP address, optionally in host:port form. Default: 127.0.0.1. An IPv6 address with a port is written as [address]:port. Since 6.2.2

-p, --port

Server TCP port. Default: the port from -H, otherwise 4701. Overrides a port given in -H. Since 6.2.2

-u, --user

Login user name. Default: admin. Ignored when -t is given.

-P, --password

User password, in clear text or encrypted with nxencpasswd for the login given with -u. If omitted when running from a terminal, the password is prompted for; otherwise an empty password is used. Ignored when -t is given.

-t, --token

Log in using the given authentication token instead of user name and password.

-n

Do not synchronize objects and the user database on connect. Lookups in the local object cache, such as session.findObjectByName(), session.findObjectById(), and session.getAllObjects(), then find nothing.

-r, --properties

File with additional Java properties (see Java Properties).

-C, --classpath

Additional Java class path.

-j, --jre

JRE location. By default, the Java runtime is located automatically.

-D, --debug

Show additional debug output. Use twice for extra output (JNI and class loading).

-v, --version

Display version information and exit.

-h, --help

Display help message and exit.

Java Properties

NXShell takes its connection settings from Java properties. The nxshell launcher sets them from its command-line options; when the JAR file is started directly, pass them with -D.

Property Description

netxms.server

Server address, optionally in host:port form. Default: 127.0.0.1.

netxms.port

Server TCP port; overrides a port given in netxms.server. Default: the port from netxms.server, otherwise 4701.

netxms.login

Login user name. Default: admin.

netxms.password

User password. Default: empty.

netxms.token

Authentication token. When set, token authentication is used and login and password are neither used nor prompted for.

netxms.enableCompression

Enable protocol compression. Default: true.

netxms.syncObjects

Synchronize objects and the user database on connect. Default: true.

nxshell.interactive

When set to any value, forces interactive mode (prompts for missing connection details, shows the console prompt). By default, interactive mode is used when standard input is a terminal.

nxshell.debug

When set to any value, enables debug-level logging of the client library to the console. Set by -D.

nxshell.logfile

Write the client library log, at debug level, to this file instead of the console. The file is rotated daily, and 30 days are kept.

nxshell.properties

Name of a file with additional properties. Set by -r.

Properties are loaded in this order, later sources overriding earlier ones:

  1. Java system properties, including those set by the nxshell launcher from its command-line options

  2. nxshell.properties on the class path or in the current directory

  3. The file named by the nxshell.properties property

As a result, a property file overrides the corresponding command-line options.

Running NXShell

NXShell can be run with the nxshell launcher or by starting its JAR file directly.

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

The JAR file nxshell-VERSION.jar is installed in the NetXMS Java library directory together with the jars it depends on, which its manifest references:

java -jar nxshell-VERSION.jar

When started this way in interactive mode, NXShell prompts for the server address (and port), login, and password if they are not given as Java properties.

java -Dnetxms.server=127.0.0.1 -Dnetxms.login=admin -jar nxshell-VERSION.jar
Passing passwords on the command line exposes them in shell history and process listings. For non-interactive use (scripts), prefer token authentication (-t option). When running from a terminal, omit -P to be prompted for the password.

Session API

NXShell provides access to the NetXMS session object (org.netxms.client.NXCSession), connected and logged in when the shell starts and bound as both session and the short alias s.

Commonly used org.netxms.base, org.netxms.client, and org.netxms.client.* subpackages (objects, datacollection, events, constants, users, topology, maps, and others) are wildcard-imported at startup, so class names like NXCObjectModificationData resolve without explicit imports. NXShell embeds Jython 2.7 (Python 2 syntax), and __name__ is set to __nxshell__ — if __name__ == "__main__": guards will not fire in nxshell scripts.

Object Methods

Method Description

session.findObjectByName(name)

Find object by name (case-insensitive) in the local object cache. If several objects have the same name, any one of them is returned; None if not found

session.findObjectById(id)

Find object by numeric ID in the local object cache

session.getAllObjects()

Get all objects from the local object cache

session.createObject(creationData)

Create a new object; returns the ID of the new object

session.modifyObject(modificationData)

Modify object properties

session.deleteObject(objectId)

Delete an object

Data Collection Methods

Method Description

session.openDataCollectionConfiguration(nodeId)

Open the DCI configuration for a node

session.getLastValues(nodeId)

Get last DCI values for a node

session.getCollectedData(nodeId, dciId, from, to, maxRows, valueType)

Get historical DCI data as a DataSeries (use .getValues() for the rows). maxRows of 0 means no limit; valueType is a HistoricalDataType value (PROCESSED, RAW, RAW_AND_PROCESSED)

Alarm Methods

Method Description

session.getAlarms()

Get all active alarms as a map of alarm ID to alarm object (terminated alarms are not included)

session.acknowledgeAlarm(alarmId)

Acknowledge an alarm

session.resolveAlarm(alarmId)

Resolve an alarm

session.terminateAlarm(alarmId)

Terminate an alarm

Action Methods

Method Description

session.executeAction(nodeId, action, args)

Execute agent action

session.executeScript(objectId, script, parameters, listener)

Execute NXSL script in the context of an object

Helper Classes

Class Description

NXCObjectCreationData

Data holder for creating new objects. Pass object class, object name, and parent ID.

NXCObjectModificationData

Data holder for modifying existing objects. Pass object ID.