SSH Monitoring

NetXMS can collect monitoring data from remote systems by executing commands over SSH. This is useful for monitoring systems where installing the NetXMS agent is not possible or practical.

Overview

SSH monitoring allows NetXMS to:

  • Execute commands on remote hosts and collect their output as metrics

  • Run scripts and collect structured data

  • Monitor systems that only allow SSH access (appliances, embedded devices, hardened systems)

The NetXMS server has no SSH client of its own. All SSH operations are executed by an agent with the ssh.nsm subagent loaded, selected via the node’s SSH proxy setting. By default this is the agent on the management server itself, so out of the box SSH connections originate from the server host — but they are always made by an agent, not by the server process.

Configuring SSH on a Node

Configure SSH credentials on the target node:

  1. Open the node properties in the management client

  2. Go to the dedicated SSH property page

  3. Configure SSH settings:

    • SSH proxy (agent that performs the SSH connections; default: management server’s agent)

    • SSH login

    • SSH password or key

    • SSH port (default: 22)

Creating SSH DCIs

  1. Create a new DCI on the target node

  2. Set the origin to SSH

  3. In the Metric field, enter the command to execute

  4. Set the data type according to the expected output

The command output (stdout) becomes the DCI value. For numeric metrics, the output must be a single number.

Example SSH DCIs

Monitor disk usage on a remote Linux system:

df -h / | tail -1 | awk '{print $5}' | tr -d '%'

Check the number of active connections:

ss -s | grep estab | awk '{print $4}' | tr -d ','

Get system uptime in seconds:

cat /proc/uptime | awk '{print $1}'

SSH Subagent (ssh.nsm)

The ssh.nsm subagent performs SSH commands on behalf of the server and must be loaded on whichever agent acts as the SSH proxy. Loading it on an agent close to the target systems is useful when those systems are not directly reachable from the server network.

Configuration

SubAgent = ssh.nsm

[SSH]
ConnectTimeout = 2000
SessionIdleTimeout = 300
Parameter Default Description

ConnectTimeout

2000

SSH connection timeout in milliseconds

SessionIdleTimeout

300

Idle session timeout in seconds (sessions are reused within this window)

ConfigFile

Path to SSH config file (default: ~/.ssh/config)

SSH Metrics

The SSH subagent provides these metrics:

Parameter Description

SSH.Command(target[:port],login,password,command[,pattern[,ssh_key_id]])

Execute command via SSH and return output

SSH.CheckConnection(target[:port],login,password[,ssh_key_id])

Check SSH connectivity; returns 1 on success, 0 on failure

SSH.CheckCommandMode(target[:port],login,password[,ssh_key_id[,command[,pattern]]])

Check SSH exec mode works; returns 1 if pattern matches output

SSH.CheckShellChannel(target[:port],login,password[,ssh_key_id[,promptPattern[,terminalType]]])

Check interactive shell channel; returns 1 if prompt detected

SSH.Command arguments:

Argument Description

target

Hostname or IP address, optionally with :port suffix (e.g. 192.168.1.1:22)

login

SSH username

password

SSH password

command

Shell command to execute via SSH exec channel

pattern

(optional) PCRE regex. If set, returns the first matching line (or first capture group). If empty, returns the first line of output.

ssh_key_id

(optional) Numeric ID of an SSH key pair stored in NetXMS configuration

SSH.Command is also available as a list (returns all output lines) and as an action. Note that the list form has no pattern argument — the SSH key ID is its fifth argument: SSH.Command(target[:port],login,password,command[,ssh_key_id]).

SSH Proxy Mode

SSH collection always follows this path:

  1. The server sends the SSH command request to the proxy agent (the management server’s agent unless another proxy is configured)

  2. The proxy agent connects to the target via SSH

  3. The command is executed on the target

  4. The output is returned through the proxy agent to the server

Configure the SSH proxy on the node’s SSH property page.

When using the SSH data origin for DCIs, the DCI metric name is the command itself. The server automatically constructs the full SSH.Command(…​) call using the node’s SSH credentials and key configuration.

SSH Key Management

NetXMS provides centralized SSH key pair management in the SSH Keys view of the Configuration perspective:

  • Generate RSA key pairs directly in the management console

  • Store keys securely in the NetXMS database

  • Associate keys with nodes for passwordless authentication

  • Keys are automatically distributed to proxy agents when needed

To use SSH key authentication:

  1. Create a key pair in the SSH Keys view (Configuration perspective)

  2. Copy the public key to the target system’s authorized_keys

  3. On the node’s SSH property page, select the SSH key

  4. The key ID is passed automatically in all SSH operations for that node

Managing SSH keys requires the Manage SSH keys system access right. Deleting a key that is in use by any node is prevented (unless force-deleted).

Interactive SSH Sessions

NetXMS supports interactive SSH sessions for devices that do not support the exec channel (e.g. Cisco IOS, Juniper, MikroTik routers).

Interactive sessions use a PTY (pseudo-terminal) channel instead of the exec channel. Network device drivers (NDDs) provide device-specific hints for terminal type, prompt regex, and pagination patterns.

NXSL Integration

Interactive SSH sessions are available via NXSL:

$session = $node->openSSHSession()
$output = $session->execute("show interfaces")
$session->close()

openSSHSession accepts optional arguments user, password, and keyId to override the node’s configured SSH credentials.

The SSHSession NXSL object provides:

  • execute(command[,timeout]) — run a command, returns array of output lines

  • escalatePrivilege(password) — send enable/su password, returns boolean

  • close() — close the channel

  • .connected, .privileged — boolean attributes

  • .nodeId — ID of the node the session belongs to

  • .lastError, .lastErrorMessage — error information

Limitations

  • SSH connection overhead makes it slower than native agent monitoring

  • Sessions are cached and reused within the idle timeout window

  • Complex output parsing may require transformation scripts or patterns

  • Binary data and non-text output are not supported

  • The remote command must complete within the polling timeout

Troubleshooting

Connection Failures

  1. Verify SSH connectivity manually from the server/agent host

  2. Check firewall rules between the server/agent and the target

  3. Verify credentials (password or key)

  4. Check SSH port configuration

  5. Review server or agent logs for SSH error messages

Incorrect Values

  1. Test the command manually via SSH and verify output format

  2. Ensure the command produces a single value (for numeric DCIs)

  3. Use a transformation script if output parsing is needed

  4. Check for locale differences that might affect number formatting (comma vs. period for decimals)