Server Hooks

NetXMS provides a hook mechanism that allows you to execute custom NXSL scripts in response to specific server events. Hooks are a powerful way to extend server behavior without modifying core functionality.

How Hooks Work

A hook is an NXSL script that the server executes automatically when a specific event occurs. Hooks are stored in the Script Library with names following the Hook:: naming convention. At each hook point the server looks up the script by its exact name in the Script Library and executes it if found — no registration or activation step is needed, and renaming or deleting the script immediately disables the hook.

Available Hook Points

Hook Parameters Description Return value

Hook::StatusPoll

$object, $node (node objects only)

Executed at the end of status poll

none

Hook::ConfigurationPoll

$object, $node (node objects only)

Executed during configuration poll, after capability and interface discovery but before automatic template and container binding (for access points, at the start of the poll)

none

Hook::InstancePoll

$object, $node (node objects only)

Executed after instance discovery poll

none

Hook::TopologyPoll

$node

Executed at the end of topology poll

none

Hook::DiscoveryPoll

$node

Executed at the end of discovery poll

none

Hook::CreateInterface

$node, $1 (Interface)

Executed when a new interface is created automatically (not for manually created interfaces)

true to allow creation; false or a script runtime error prevents it

Hook::UpdateInterface

$node, $interface, $1 (same Interface object)

Executed at the end of interface update

none

Hook::CreateSubnet

$node, $1 (Subnet)

Executed on subnet creation

true to allow creation; false or a script runtime error prevents it

Hook::AcceptNewNode

$ipAddress, $ipAddr, $ipNetMask, $macAddress, $macAddr, $zoneUIN

Executed during network discovery before node creation

Only an explicit false (or a script runtime error) prevents node creation; returning null or nothing accepts the node

Hook::DiscoveryFilter

$node (DiscoveredNode), $snmp (when available)

Executed as an additional filter for each node found by network discovery

true to accept the node; false or a script runtime error rejects it

Hook::PostObjectCreate

$object, $node (node objects only)

Executed after any object has been created

none

Hook::ObjectDelete

$object, $node (node objects only)

Executed before an object is deleted

none

Hook::EventProcessor

$object, $node (node objects only), $event

Executed for each event before EPP processing

none

Hook::AlarmStateChange

$alarm

Executed asynchronously when an alarm changes state

none

Hook::OpenUnboundTunnel

$tunnel

Executed when an unbound agent tunnel is established

none

Hook::OpenBoundTunnel

$node, $tunnel

Executed when a bound agent tunnel connects

none

Hook::LDAPSynchronization

$ldapObject

Executed for each LDAP record during synchronization

Only an explicit false blocks processing of the record; null or a script runtime error does not block

Hook::Login

$user, $session

Executed prior to user login

Only an explicit false blocks the login; null or a script runtime error does not block

Hook::RegisterForConfigurationBackup

$node

Determines whether a node should be registered for device configuration backup. Default script: return $node.isSNMP;

true to register the node

Every object hook receives $object set to the object being processed; $node is additionally defined only when that object is a node. $isCluster is always set (true when the object is a cluster), and $map is additionally defined when the object is a network map. Hook::StatusPoll also runs for clusters, sensors, and other polled object types — but not for access points or wireless domains, which run only Hook::ConfigurationPoll. In non-node runs $node is not defined, and scripts must not assume it. Guard node-specific logic with if ($node != null) or check classof($object).

Hook::AcceptNewNode Variables

Variable Description

$ipAddress

Primary IP address of the new node (InetAddress object)

$ipAddr

Primary IP address as a string

$ipNetMask

Network mask length in bits (integer)

$macAddress

MAC address of the new node (MacAddress object)

$macAddr

MAC address as a string

$zoneUIN

Zone UIN of the new node

Configuring Hooks

  1. Open the management client

  2. Navigate to Configuration > Script Library

  3. Create a new script with the exact hook name (e.g., Hook::ConfigurationPoll)

  4. Write the hook logic in NXSL

The script takes effect immediately — the server looks it up by name each time the hook point is reached.

Hook Examples

Auto-Accept Nodes from Specific Subnets

This Hook::AcceptNewNode script accepts nodes only from specific IP ranges:

if ($ipAddr like "10.*" || $ipAddr like "172.16.*" || $ipAddr like "172.17.*")
    return true;
return false;

Filter Interfaces During Discovery

This Hook::CreateInterface script prevents creation of loopback and tunnel interfaces (the interface object is passed as $1):

if ($1.name like "lo*" || $1.name like "tun*" || $1.name like "veth*")
    return false;
return true;

Auto-Bind Agent Tunnels

This Hook::OpenUnboundTunnel script automatically binds agent tunnels based on the agent’s system name:

hostname = $tunnel.systemName;
node = FindNodeBySysName(hostname);
if (node != null) {
    $tunnel.bind(node);
}

Custom Configuration Poll Logic

This Hook::ConfigurationPoll script adds custom attributes during configuration poll:

osName = $node.sysDescription;
if (osName like "*Ubuntu*") {
    $node.setCustomAttribute("os_family", "debian");
} else if (osName like "*CentOS*" || osName like "*Red Hat*") {
    $node.setCustomAttribute("os_family", "rhel");
}

Event Processing Hook

This Hook::EventProcessor script enriches events with additional data:

sourceNode = FindObject($event.sourceId);
if (sourceNode != null) {
    location = sourceNode.getCustomAttribute("location");
    if (location != null) {
        $event.setNamedParameter("location", location);
    }
}

Debugging Hooks

For where and how to change server debug levels, see Enabling Debug Logging.

To debug hook execution, enable debug logging for the relevant tags:

debug nxsl.hooks 7
debug obj.lifecycle 7
debug scripts 7

Script runtime errors are logged with the scripts tag. Execution of the object hooks (status, configuration, instance, topology, and discovery polls; object creation and deletion) is logged with the obj.lifecycle tag. The nxsl.hooks tag covers only Hook::AcceptNewNode and Hook::DiscoveryFilter; other hooks log load failures under their subsystem tags (for example poll.conf, node.iface, alarm, ldap, agent.tunnel).

You can also use the trace() function within hook scripts to output debug information:

trace(1, "Hook::ConfigurationPoll called for " .. $node.name);
Long-running hook scripts can affect server performance. Keep hook logic efficient and avoid blocking operations.

See NXSL Reference for the complete scripting language documentation.