Service Monitoring

NetXMS can monitor the availability of network services by performing active checks through an agent. Service monitoring verifies that TCP services (HTTP, SMTP, POP3, SSH, and custom services) are responding correctly.

Overview

Service monitoring works by connecting to a service port, optionally performing protocol-specific handshakes, and verifying the response. This provides end-to-end availability verification from the perspective of the monitoring system.

All service checks are performed by an agent with the netsvc.nsm subagent loaded. The server itself has no built-in service checker: even server-managed Network Service objects delegate the actual check to an agent (the configured poller node’s agent, or the agent on the management server by default). Checks can be used in two ways:

  • Network Service objects — the server periodically requests a check from an agent and generates events on state changes

  • Agent metrics — DCIs collecting netsvc.nsm metrics directly

Agent-Side Service Checks (netsvc.nsm)

The netsvc.nsm subagent performs network service checks from the agent host. It also provides TLS certificate monitoring and HTTP content verification.

SubAgent = netsvc.nsm

Subagent Configuration

The [netsvc] section in the agent config controls global defaults:

Parameter Default Description

CA

Path to custom CA bundle file for TLS verification

DomainName

example.org

Domain name used for SMTP from address (noreply@DomainName)

NegativeResponseTimeOnError

false

Return negative response time instead of error when service check fails

Timeout

1000

Default timeout in milliseconds for all checks

VerifyPeer

true

Default TLS peer certificate verification

Service Status and Response Time

Parameter Description

NetworkService.Status(url[,named-params…​])

Check network service availability. Returns: 0 = success, 2 = connection error, 3 = response mismatch, 4 = internal error, 5 = handshake error. Invalid or missing parameters result in a metric error (only the legacy ServiceCheck.* metrics return 1 in that case).

NetworkService.ResponseTime(url[,named-params…​])

Service response time in milliseconds

NetworkService.TLSStatus(host,port[,named-params…​])

Check TLS/SSL connection status. Only the timeout named parameter is supported.

NetworkService.TLSResponseTime(host,port[,named-params…​])

TLS handshake time in milliseconds. Only the timeout named parameter is supported.

Named Parameters

The NetworkService.Status and NetworkService.ResponseTime metrics accept a URL as the first argument, followed by optional named parameters in name=value form:

Parameter Applies To Description

resolve

All

Override DNS; connect to this IP address but use URL hostname for TLS SNI

timeout

All

Connection/operation timeout in milliseconds

follow-location

HTTP/HTTPS

Follow HTTP 3xx redirects (default: false)

include-headers

HTTP/HTTPS

Match pattern in headers + body when true, body only when false (default: true)

pattern

HTTP/HTTPS

PCRE regex pattern to match in the response

response-code

HTTP/HTTPS

Expected HTTP response code

verify-peer

TLS-based

Verify TLS peer certificate (default: global VerifyPeer setting)

verify-host

TLS-based

Verify hostname matches certificate (default: true)

tls-mode

FTP/IMAP/POP3/SMTP

TLS mode: none, try, or always

login

Authenticated

Username for authentication

password

Authenticated

Password (supports nxencpasswd-obfuscated values)

to

SMTP/SMTPS

Destination address for test email (required for SMTP checks)

from

SMTP/SMTPS

Sender address (default: noreply@DomainName)

subject

SMTP/SMTPS

Email subject for test message

text

SMTP/SMTPS

Email body text for test message

Example with named parameters:

NetworkService.Status(https://example.com/api/health,timeout=5000,pattern=OK,verify-peer=true)

TLS Certificate Monitoring

TLS.Certificate.ExpiresIn(host,port[,sniServerName[,startTlsProto]])
Parameter Description

TLS.Certificate.ExpiresIn(host,port,…​)

Days until certificate expiration

TLS.Certificate.ExpirationDate(host,port,…​)

Certificate expiration date (YYYY-MM-DD)

TLS.Certificate.ExpirationTime(host,port,…​)

Certificate expiration as Unix timestamp

TLS.Certificate.Issuer(host,port,…​)

Certificate issuer

TLS.Certificate.Subject(host,port,…​)

Certificate subject

TLS.Certificate.TemplateID(host,port,…​)

Certificate template ID (Active Directory Certificate Services)

Arguments:

  • host — hostname or IP address

  • port — TCP port number

  • sniServerName — (optional) SNI server name override, useful when connecting to an IP address

  • startTlsProto — (optional) StartTLS protocol: smtp, imap, or pop3

HTTP Content Verification

Parameter Description

HTTP.Checksum.MD5(url[,named-params…​])

MD5 checksum of HTTP response body

HTTP.Checksum.SHA1(url[,named-params…​])

SHA1 checksum of HTTP response body

HTTP.Checksum.SHA256(url[,named-params…​])

SHA256 checksum of HTTP response body

Named parameters: follow-location, login, password, resolve, timeout, tls-mode, verify-host, verify-peer.

Legacy Metrics (portcheck compatibility)

The netsvc.nsm subagent also supports legacy metric names for backward compatibility with the older portcheck.nsm subagent:

Parameter Description

ServiceCheck.Custom(host,port[,timeout])

Custom TCP port check

ServiceCheck.HTTP(host,[port],uri[,hostHeader[,match[,timeout]]])

HTTP service check. Only host and uri are required; port may be left empty (default: 80).

ServiceCheck.HTTPS(host,[port],uri[,hostHeader[,match[,timeout]]])

HTTPS service check. Only host and uri are required; port may be left empty (default: 443).

ServiceCheck.POP3(host,user,pass[,timeout[,port]])

POP3 service check

ServiceCheck.POP3S(host,user,pass[,timeout[,port]])

POP3S service check

ServiceCheck.SMTP(host,recipient[,timeout[,port]])

SMTP service check

ServiceCheck.SMTPS(host,recipient[,timeout[,port]])

SMTPS service check

ServiceCheck.SSH(host[,port[,timeout]])

SSH service check

ServiceCheck.Telnet(host[,port[,timeout]])

Telnet service check

ServiceCheck.TLS(host,port[,named-params…​])

TLS service check. Only the timeout named parameter is supported.

Corresponding ServiceResponseTime.* metrics return response time in milliseconds instead of status. Note that ServiceResponseTime.SMTPS does not exist.

Network Service Objects

The NetXMS server supports creating Network Service objects for automated service polling. A Network Service object is a child of a Node and periodically checks a specific service. The server does not perform the check itself — it delegates it to an agent (the configured poller node, or the management server’s agent by default).

There are no default port numbers: the TCP port must be set explicitly (1-65535) for every service type.

Service types:

Type Description

User-defined

Generic TCP connection check

SSH

SSH connection check

POP3

POP3 mailbox check (request: user:password)

SMTP

SMTP relay check (request: recipient email)

FTP

Selectable in the UI, but not implemented by the agent — the check always fails. Use a User-defined (TCP) check instead.

HTTP

HTTP check (request: hostHeader:uri, response: match pattern)

HTTPS

HTTPS check

Telnet

Telnet connection check

The protocol additionally defines TLS, POP3S, and SMTPS service types, but these are not selectable in the management client dialogs.

Network Service objects generate these events on state change:

  • SYS_SERVICE_UP — service became available

  • SYS_SERVICE_DOWN — service became unavailable

  • SYS_SERVICE_UNKNOWN — service status cannot be determined

To create a Network Service object: right-click a node, select Create  Network Service, configure the service type, port, request/response strings, and optionally set a poller node. The Required Poll Count setting controls how many consecutive polls must confirm a state change before generating an event.

Monitoring Examples

HTTP Check with Content Pattern

NetworkService.Status(https://example.com/api/health,pattern=status.*healthy,timeout=5000)

HTTP Check with Response Code Verification

NetworkService.Status(https://api.example.com/status,response-code=200)

HTTPS Certificate Expiration

TLS.Certificate.ExpiresIn(example.com,443)

TLS Certificate with StartTLS (SMTP)

TLS.Certificate.ExpiresIn(mail.example.com,587,,smtp)

SMTP Service Check

NetworkService.Status(smtp://mail.example.com,[email protected])

HTTP Check via Specific IP (DNS Override)

NetworkService.Status(https://api.example.com/health,resolve=10.0.0.5,timeout=3000)

POP3 with TLS

NetworkService.Status(pop3://mail.example.com,tls-mode=always,login=monitor,password=your_password)

Content Integrity Monitoring

HTTP.Checksum.SHA256(http://example.com/critical-page,follow-location=true)

Custom TCP Port Check (Legacy)

ServiceCheck.Custom(192.168.1.10,6379,5000)

SSH Service Check (Legacy)

ServiceCheck.SSH(192.168.1.10,22,3000)

Telnet Service Check (Legacy)

ServiceCheck.Telnet(192.168.1.10,23,3000)

Windows Service Monitoring

On Windows systems, the agent can monitor Windows services:

Parameter Description

System.ServiceState(name)

State of a Windows service (see value table below)

System.Services

List of all service names; also available as a table with service state, start type, and related details

The System.Services list and table are not Windows-specific — they are also provided by the Linux agent (see below).

System.ServiceState values on Windows:

Value Meaning

0

Running

1

Paused

2

Start pending

3

Pause pending

4

Continue pending

5

Stop pending

6

Stopped

7

Unknown state (reported service state did not match any known state)

Querying a service that does not exist results in a metric collection error, not a value of 7.

To monitor that a critical Windows service is running:

  1. Create a DCI with metric System.ServiceState(servicename)

  2. Set a threshold: alert when value is not 0 (not running)

Linux Systemd Service Monitoring

On Linux systems with systemd, monitor service status with the same System.ServiceState(name) metric. The agent uses the appropriate service management framework based on the platform, but the returned values differ from Windows — systemd uses a sparse set:

Value Meaning

0

Running (active)

2

Starting (activating)

5

Stopping (deactivating)

6

Stopped (inactive)

7

Failed

-1

Unknown state

The System.Services list (service names) and table are available on Linux as well; with systemd the table provides 9 columns of unit information.

Troubleshooting

False Positives

If service checks report false failures:

  • Increase the timeout value

  • Check for firewall rules that might block the monitoring connection

  • Verify the service is accessible from the agent host performing the check

  • Check if the service requires authentication that is not configured

Connection Refused vs. Timeout

  • Connection refused — the host is reachable but no service is listening on the port

  • Connection timeout — the host or port is unreachable (firewall, network issue)

  • Both result in a "down" status, but the distinction helps troubleshooting