This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

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 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 Communication > 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

The ssh 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

[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. All of them take the same first arguments:

Argument Description

target

Host name or IP address, optionally with a :port suffix (for example 192.168.1.1:2222; default port 22)

login

SSH user name

password

SSH password

ssh_key_id

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

SSH.Command

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

Run a command over the SSH exec channel and return its output.

Argument Description

command

Command to run

pattern

(optional) PCRE regular expression. If set, the metric returns the first matching line, or the first capture group; if empty, the first line of output.

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

SSH.CheckConnection

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

Check that an SSH session can be established; returns 1 on success, 0 on failure.

SSH.CheckCommandMode

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

Check that commands run over the SSH exec channel; returns 1 when a line of the command output matches the pattern, 0 otherwise.

Argument Description

command

(optional) Command to run (default: echo netxms_test_12345)

pattern

(optional) Regular expression to look for in the output (default: netxms_test_12345)

SSH.CheckShellChannel

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

Check that an interactive shell channel opens and shows a prompt; returns 1 when the prompt is detected, 0 otherwise.

Argument Description

promptPattern

(optional) Regular expression for the shell prompt (default: [>$#]\s*$, a line ending in >, $, or #)

terminalType

(optional) Terminal type requested for the channel (default: vt100)

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 on the server, or import existing private keys

  • 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 with Generate…​, or import one with Import…​, in the SSH Keys view (Configuration perspective)

  2. Select the key and use Copy public key to clipboard, then add the copied line 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

When a node has an SSH key, the agent tries public-key authentication first. If that does not authenticate the session, it tries the node’s password, then keyboard-interactive authentication with the same password.

For keys generated or imported in 7.0.3 or later, the copied public key is one line in the format <type> <base64 key> <key name>. The name in it is the key name at the time the key pair was generated, imported, or replaced. Renaming the key without replacing its private key does not change this line.

Key names must not be blank and can have at most 254 characters. The server rejects longer names; it does not truncate them.

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).

The ssh and netconf subagents cache keys on the proxy agent. When a cached key is requested after five minutes, the proxy revalidates it with the server, fetching the current key pair or removing it from the cache if the server reports that it no longer exists. If the server cannot be reached or another refresh error occurs, the proxy keeps using its cached copy and waits at least 60 seconds before retrying. For locally cached data collection, key requests use a live connection to the same server when one is available.

Importing a Key

Import…​ asks for a name and a private key. The server derives the public key from the private key and stores both; you do not supply the public key.

The private key must be an unencrypted OpenSSH private key, which starts with -----BEGIN OPENSSH PRIVATE KEY-----. This is the default format of ssh-keygen since OpenSSH 7.8. Supported key types are ssh-ed25519, ssh-rsa, and ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521.

The server rejects these keys:

  • PEM (PKCS#1) keys, such as -----BEGIN RSA PRIVATE KEY-----

  • PKCS#8 keys (-----BEGIN PRIVATE KEY-----, -----BEGIN ENCRYPTED PRIVATE KEY-----)

  • Keys protected with a passphrase

  • Hardware-backed keys ([email protected], [email protected]) and certificates

These rules apply when a key is imported or replaced. Keys generated on the server, and keys stored before the upgrade to 7.0.3, are not changed.

When the server rejects the key, the console shows "Invalid private key" and opens the dialog again with the data you entered.

To convert a key in another format, or to remove its passphrase, rewrite a copy of the key file with ssh-keygen:

ssh-keygen -p -N "" -f <file>

ssh-keygen asks for the current passphrase if there is one. Keep -N "": without it, ssh-keygen -p asks for a new passphrase and can leave the key encrypted.

Editing a Key

Edit…​ shows the current public key as read-only text and has an optional New private key field:

  • Leave New private key empty to rename the key. The key pair does not change.

  • Paste a private key to replace the key pair. The same format rules as for import apply.

SSH Terminal in the Console

Right-click a node and select Tools > SSH terminal…​ to open an interactive terminal in the desktop or web console. The connection dialog offers two modes:

  • Through SSH proxy — the node’s SSH proxy agent establishes the SSH session. Use the node’s stored credentials or supply a login, password, and server-side SSH key.

  • Direct SSH from console over TCP proxy — the console establishes the SSH session through a TCP proxy channel. Supply a login and password; the desktop console can also use a local private key file. The web console supports password authentication for this mode.

Both modes use the node’s SSH port by default. Direct mode requires TCP proxy access; proxy mode requires the ssh subagent on the selected SSH proxy agent. External applications can open the same proxy-based terminal using the WebAPI SSH terminal endpoint.

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)