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:
-
Open the node properties in the management client
-
Go to the Communication > SSH property page
-
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)
-
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 |
|---|---|---|
|
2000 |
SSH connection timeout in milliseconds |
|
300 |
Idle session timeout in seconds (sessions are reused within this window) |
|
Path to SSH config file (default: |
SSH Metrics
The SSH subagent provides these metrics. All of them take the same first arguments:
| Argument | Description |
|---|---|
|
Host name or IP address, optionally with a |
|
SSH user name |
|
SSH password |
|
(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 to run |
|
(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 |
|---|---|
|
(optional) Command to run (default: |
|
(optional) Regular expression to look for in the output (default: |
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 |
|---|---|
|
(optional) Regular expression for the shell prompt (default: |
|
(optional) Terminal type requested for the channel (default: |
SSH Proxy Mode
SSH collection always follows this path:
-
The server sends the SSH command request to the proxy agent (the management server’s agent unless another proxy is configured)
-
The proxy agent connects to the target via SSH
-
The command is executed on the target
-
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:
-
Create a key pair with Generate…, or import one with Import…, in the SSH Keys view (Configuration perspective)
-
Select the key and use Copy public key to clipboard, then add the copied line to the target system’s
authorized_keys -
On the node’s SSH property page, select the SSH key
-
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.
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