NETCONF Monitoring
NetXMS retrieves values from network devices over NETCONF through an agent running the netconf subagent.
The proxy agent opens an SSH netconf subsystem session, exchanges hello messages, retrieves XML with get or get-config, and extracts DCI values using XPath.
The same proxy also supports NETCONF operations used by network device drivers, including device configuration backup and restore.
NXSL scripts can use the same proxy through NETCONFSession.
How It Works
NETCONF collection follows the target node’s NETCONF proxy setting and uses the node’s SSH login, password, and key. When no proxy is selected explicitly, the server uses the zone proxy when applicable, otherwise the management server’s agent. The target device does not need a NetXMS agent.
The proxy reuses sessions by target address, port, and login.
It also caches retrieved documents by target, login, datastore, and filter.
Different XPath expressions using the same document can share that cache.
The query definition’s Cache retention time controls refresh; the agent’s CacheExpirationTime controls removal of documents that are no longer queried.
A refresh failure is returned as an error; the old document is not served as a successful refresh.
Enabling NETCONF Monitoring
-
Enable NETCONF over SSH on the target device and allow connections from the proxy agent to the device’s NETCONF port (normally TCP 830).
-
On the proxy agent, load the subagent in
nxagentd.confand restart the agent:SubAgent = netconf -
In the target node’s properties, set the proxy and port under Communication > NETCONF.
-
Set the login, password, and optional key under Communication > SSH. NETCONF uses these credentials but its own port and proxy settings. For stored keys, see SSH Key Management.
-
Run a configuration poll on the target node to detect NETCONF support and capabilities.
Creating NETCONF DCIs
-
In Configuration > NETCONF queries, create a named query definition. Choose Operational (get) for operational data, or a configuration datastore for
get-config; set any device-side filter, cache retention time, and request timeout. -
Create a DCI on the target node with origin NETCONF.
-
Set the metric to
<query-name>:<xpath>, where the XPath addresses the returned document under/data/…. -
Select the data type for the extracted value and configure the polling interval.
For example, a query definition named interfaces and an XPath /data/interfaces/interface[name='eth0']/statistics/in-octets are combined as:
interfaces:/data/interfaces/interface[name='eth0']/statistics/in-octets
The path must match the XML returned by your device and the selected filter. For all query-definition fields, see DCI Configuration Reference.
Agent Configuration
Optional parameters in the proxy agent’s nxagentd.conf:
[NETCONF]
ConnectTimeout = 5000
RequestTimeout = 60000
SessionIdleTimeout = 300
CacheExpirationTime = 600
| Parameter | Default | Description |
|---|---|---|
|
|
SSH connection timeout in milliseconds, also used when waiting for the device hello message. |
|
|
Default RPC response timeout in milliseconds. A nonzero timeout in the query definition overrides this value. |
|
|
Idle session lifetime in seconds. A housekeeper checks sessions every 30 seconds and closes unused idle or disconnected sessions. |
|
|
Seconds without a query before a document becomes eligible for removal by the housekeeper. This is separate from the query definition’s cache retention time, which controls when data is refreshed. |
Agent Health Check and Capabilities
These are direct agent metrics on the proxy agent. They take explicit target credentials; ordinary NETCONF-origin DCIs use the node’s stored settings instead.
Provided by the netconf subagent on the agent that connects to the target device.
These agent metrics are separate from DCIs with origin NETCONF, which use a named query definition and an XPath expression.
Both entries below accept the same arguments; the key ID is optional.
The health check and capability list can reuse an existing pooled session.
Metrics
NETCONF.CheckConnection(target,login,password[,ssh_key_id])
Returns 1 when a NETCONF session is acquired, including SSH authentication, the netconf subsystem, and the NETCONF hello exchange when opening a new session.
Returns 0 for connection, authentication, or handshake failure and for an invalid target address.
Invalid argument syntax is reported as unsupported.
No retrieval RPC is sent by this check.
Data Type |
Integer |
Platforms |
Windows, UNIX-like systems |
| Argument | Type | Description |
|---|---|---|
target |
String |
Host name or IPv4 address, optionally with |
login |
String |
SSH user name |
password |
String |
SSH password; supply an empty argument when using only a key |
ssh_key_id |
Unsigned Integer |
Optional ID of an SSH key pair stored on the NetXMS server; default 0 (no key). The agent obtains the pair from the connected server. |
Lists
NETCONF.Capabilities(target,login,password[,ssh_key_id])
Capability URIs announced by the device in its NETCONF hello message. A connection or target-address failure returns a collection error.
Data Type |
List |
Platforms |
Windows, UNIX-like systems |
| Argument | Type | Description |
|---|---|---|
target |
String |
Host name or IPv4 address, optionally with |
login |
String |
SSH user name |
password |
String |
SSH password; supply an empty argument when using only a key |
ssh_key_id |
Unsigned Integer |
Optional ID of an SSH key pair stored on the NetXMS server; default 0 (no key). The agent obtains the pair from the connected server. |
Troubleshooting
-
NETCONF is not detected — check that the
netconfsubagent is loaded on the selected proxy, access from that proxy to the NETCONF port, and the node’s SSH credentials. An ordinary SSH command shell is not sufficient: the device must accept thenetconfsubsystem and complete the hello exchange. -
Connection works, but data collection fails — check the query name, datastore, filter, and XPath. XPath is evaluated below
/data, not below/rpc-reply. An empty extraction is reported as no such instance. -
Updates arrive less frequently than DCI polls — check the query definition’s cache retention time. Several DCIs can reuse one document until its retention time expires.
-
A port is blocked — check the target node’s communication port stop list; server NETCONF collection honors blocked TCP ports.
Enable agent debug tag netconf at level 6 for connection and protocol failures, or level 7 for session and document-cache reuse.
On the server, debug tag dc.netconf reports DCI query failures, and netconf reports connection checks and NETCONF operations.
See Diagnostics for setting debug levels.