CheckNet
Network related checks such as check_ping, check_tcp, check_dns, check_http, check_connections and check_ntp_offset.
Enable module
To enable this module and and allow using the commands you need to ass CheckNet = enabled to the [/modules] section in nsclient.ini:
[/modules]
CheckNet = enabled
Queries
A quick reference for all available queries (check commands) in the CheckNet module.
List of commands:
A list of all available queries (check commands)
| Command | Description |
|---|---|
| check_connections | Count active TCP/UDP connections and report counts per protocol and TCP state. |
| check_dns | Resolve a host name and check the response time and resulting addresses. |
| check_http | Send an HTTP/HTTPS request and check the response status, time, size and body. |
| check_nsclient_web_online | Query the REST API of a remote NSClient++ agent (reachability or a remote check). |
| check_ntp_offset | Query an NTP server and check the offset between the local clock and the server. |
| check_ping | Ping another host and check the result. |
| check_ssh | Connect to an SSH port and verify the server presents a valid SSH banner. |
| check_tcp | Connect to a TCP port and optionally send/expect data to check that a service is reachable. |
check_connections
Count active TCP/UDP connections and report counts per protocol and TCP state.
Jump to section:
Sample Commands
Default check (uses the total bucket):
check_connections
L cli OK: OK: total/all: 226
L cli Performance data: 'total_all_close_wait'=0;0;0 'total_all_closing'=0;0;0 'total_all_established'=90;0;0 'total_all_fin_wait'=0;0;0 'total_all_last_ack'=0;0;0 'total_all_listen'=69;0;0 'total_all_syn_recv'=0;0;0 'total_all_syn_sent'=0;0;0 'total_all_time_wait'=6;0;0 'total_all_total'=226;0;0 'total_all_udp'=61;0;0
Per-protocol breakdown (disable the default total filter):
check_connections "filter=state = 'all'" "top-syntax=%(status): %(list)" "detail-syntax=%(protocol)/%(family)=%(count)"
L cli OK: OK: tcp/ipv4=157, tcp6/ipv6=15, udp/ipv4=40, udp6/ipv6=21, total/any=233
L cli Performance data: 'tcp_all_close_wait'=0;0;0 'tcp_all_closing'=0;0;0 'tcp_all_established'=0;0;0 'tcp_all_fin_wait'=0;0;0 'tcp_all_last_ack'=0;0;0 'tcp_all_listen'=0;0;0 'tcp_all_syn_recv'=0;0;0 'tcp_all_syn_sent'=0;0;0 'tcp_all_time_wait'=0;0;0 'tcp_all_total'=0;0;0 'tcp_all_udp'=0;0;0 'tcp6_all_close_wait'=0;0;0 'tcp6_all_closing'=0;0;0 'tcp6_all_established'=0;0;0 'tcp6_all_fin_wait'=0;0;0 'tcp6_all_last_ack'=0;0;0 'tcp6_all_listen'=0;0;0 'tcp6_all_syn_recv'=0;0;0 'tcp6_all_syn_sent'=0;0;0 'tcp6_all_time_wait'=0;0;0 'tcp6_all_total'=0;0;0 'tcp6_all_udp'=0;0;0 'udp_all_close_wait'=0;0;0 'udp_all_closing'=0;0;0 'udp_all_established'=0;0;0 'udp_all_fin_wait'=0;0;0 'udp_all_last_ack'=0;0;0 'udp_all_listen'=0;0;0 'udp_all_syn_recv'=0;0;0 'udp_all_syn_sent'=0;0;0 'udp_all_time_wait'=0;0;0 'udp_all_total'=0;0;0 'udp_all_udp'=0;0;0 'udp6_all_close_wait'=0;0;0 'udp6_all_closing'=0;0;0 'udp6_all_established'=0;0;0 'udp6_all_fin_wait'=0;0;0 'udp6_all_last_ack'=0;0;0 'udp6_all_listen'=0;0;0 'udp6_all_syn_recv'=0;0;0 'udp6_all_syn_sent'=0;0;0 'udp6_all_time_wait'=0;0;0 'udp6_all_total'=0;0;0 'udp6_all_udp'=0;0;0 'total_all_close_wait'=1;0;0 'total_all_closing'=0;0;0 'total_all_established'=93;0;0 'total_all_fin_wait'=0;0;0 'total_all_last_ack'=0;0;0 'total_all_listen'=69;0;0 'total_all_syn_recv'=0;0;0 'total_all_syn_sent'=0;0;0 'total_all_time_wait'=9;0;0 'total_all_total'=233;0;0 'total_all_udp'=61;0;0
Show only TCP states:
check_connections "filter=protocol = 'tcp' and state != 'all'" "top-syntax=%(status): %(list)" "detail-syntax=%(state)=%(count)"
check_connections "filter=protocol = 'tcp' and state != 'all'" "top-syntax=%(status): %(list)" "detail-syntax=%(state)=%(count)"
L cli OK: OK: ESTABLISHED=92, LISTEN=69, TIME_WAIT=9
Warn/critical based on total connections:
check_connections "warn=total > 500" "crit=total > 1000"
L cli OK: OK: total/all: 231
Warn when many sockets are stuck in TIME_WAIT:
check_connections "filter=protocol = 'tcp' and state = 'TIME_WAIT'" "warn=count > 200" "crit=count > 1000"
L cli OK: OK: tcp/TIME_WAIT: 14
Alert on growing CLOSE_WAIT (often indicates leaks):
check_connections "filter=state = 'CLOSE_WAIT'" "warn=count > 50" "crit=count > 200"
L cli OK: No connection data
Default check via NRPE:
check_nscp_client --host 192.168.56.103 --command check_connections
OK: total/all: 231|'total_all_close_wait'=0;0;0 'total_all_closing'=0;0;0 'total_all_established'=85;0;0 'total_all_fin_wait'=0;0;0 'total_all_last_ack'=0;0;0 'total_all_listen'=69;0;0 'total_all_syn_recv'=0;0;0 'total_all_syn_sent'=1;0;0 'total_all_time_wait'=16;0;0 'total_all_total'=231;0;0 'total_all_udp'=60;0;0
Command-line Arguments
| Option | Default Value | Description |
|---|---|---|
| filter | protocol = 'total' | Filter which marks interesting items. |
| warning | total > 1000 | Filter which marks items which generates a warning state. |
| warn | Short alias for warning | |
| critical | total > 2000 | Filter which marks items which generates a critical state. |
| crit | Short alias for critical. | |
| ok | Filter which marks items which generates an ok state. | |
| debug | N/A | Show debugging information in the log |
| show-all | N/A | Show details for all matches regardless of status (normally details are only showed for warnings and criticals). |
| empty-state | ignored | Return status to use when nothing matched filter. |
| perf-config | Performance data generation configuration | |
| escape-html | N/A | Escape any < and > characters to prevent HTML encoding |
| help | N/A | Show help screen (this screen) |
| help-pb | N/A | Show help screen as a protocol buffer payload |
| show-default | N/A | Show default values for a given command |
| help-short | N/A | Show help screen (short format). |
| top-syntax | ${status}: ${list} | Top level syntax. |
| ok-syntax | %(status): %(list) | ok syntax. |
| empty-syntax | No connection data | Empty syntax. |
| detail-syntax | ${protocol}/${state}: ${count} | Detail level syntax. |
| perf-syntax | ${protocol}_${state} | Performance alias syntax. |
filter:
Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.
Default Value: protocol = 'total'
warning:
Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.
Default Value: total > 1000
critical:
Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.
Default Value: total > 2000
ok:
Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.
empty-state:
Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.
Default Value: ignored
perf-config:
Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)
top-syntax:
Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${status}: ${list}
ok-syntax:
ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).
Default Value: %(status): %(list)
empty-syntax:
Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.
Default Value: No connection data
detail-syntax:
Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${protocol}/${state}: ${count}
perf-syntax:
Performance alias syntax. This is the syntax for the base names of the performance data.
Default Value: ${protocol}_${state}
Filter keywords
| Option | Description |
|---|---|
| close_wait | Number of TCP connections in CLOSE_WAIT state (total bucket) |
| closing | Number of TCP connections in CLOSING state (total bucket) |
| established | Number of TCP connections in ESTABLISHED state (total bucket) |
| family | Address family (ipv4, ipv6, any) |
| fin_wait | Number of TCP connections in FIN_WAIT* state (total bucket) |
| last_ack | Number of TCP connections in LAST_ACK state (total bucket) |
| listen | Number of TCP sockets in LISTEN state (total bucket) |
| protocol | Protocol of this bucket (tcp, tcp6, udp, udp6, total) |
| state | TCP state name (ESTABLISHED, LISTEN, ...) or 'all' |
| syn_recv | Number of TCP connections in SYN_RECV state (total bucket) |
| syn_sent | Number of TCP connections in SYN_SENT state (total bucket) |
| time_wait | Number of TCP connections in TIME_WAIT state (total bucket) |
| udp | Number of UDP sockets (total bucket) |
Common options for all checks:
| Option | Description |
|---|---|
| count | Number of items matching the filter. |
| crit_count | Number of items matched the critical criteria. |
| crit_list | A list of all items which matched the critical criteria. |
| detail_list | A special list with critical, then warning and finally ok. |
| list | A list of all items which matched the filter. |
| ok_count | Number of items matched the ok criteria. |
| ok_list | A list of all items which matched the ok criteria. |
| problem_count | Number of items matched either warning or critical criteria. |
| problem_list | A list of all items which matched either the critical or the warning criteria. |
| status | The returned status (OK/WARN/CRIT/UNKNOWN). |
| total | Total number of items. |
| warn_count | Number of items matched the warning criteria. |
| warn_list | A list of all items which matched the warning criteria. |
check_dns
Resolve a host name and check the response time and resulting addresses.
Jump to section:
Sample Commands
Default lookup of a hostname:
check_dns host=google.com
check_dns host=google.com
L cli OK: OK: google.com -> 172.217.20.174 (1) in 10ms [ok]
L cli Performance data: 'google.com_time'=10;1000;0
Lookup with a custom timeout:
check_dns host=google.com timeout=2000
check_dns host=google.com timeout=2000
L cli OK: OK: google.com -> 172.217.20.174 (1) in 3ms [ok]
L cli Performance data: 'google.com_time'=3;1000;0
Verify the resolver returns specific addresses:
check_dns host=google.com expected-address=172.217.20.174
L cli OK: OK: google.com -> 172.217.20.174 (1) in 3ms [ok]
L cli Performance data: 'google.com_time'=3;1000;0
Verify against multiple expected addresses (comma list):
check_dns host=google.com "expected=93.184.216.34,2606:2800:220:1:248:1893:25c8:1946"
L cli CRITICAL: CRITICAL: google.com -> 172.217.20.174 (1) in 7ms [mismatch]
L cli Performance data: 'google.com_time'=7;1000;0
Tighter latency thresholds:
check_dns host=nsclient.org "warn=time > 100" "crit=time > 5 or result != 'ok'"
L cli CRITICAL: CRITICAL: nsclient.org -> 188.114.97.1,188.114.96.1 (2) in 8ms [ok]
L cli Performance data: 'nsclient.org_time'=8;100;5
Custom output text:
check_dns host=google.com "top-syntax=%(status): %(list)" "detail-syntax=%(host)=%(addresses) [%(result)]"
L cli OK: OK: google.com=172.217.20.174 [ok]
L cli Performance data: 'google.com_time'=5;1000;0
Default check via NRPE:
check_nscp_client --host 192.168.56.103 --command check_dns --argument "host=example.com"
OK: google.com -> 172.217.20.174 (1) in 10ms [ok]|'google.com_time'=10;1000;0
Query a specific record type (type=A|AAAA|MX|TXT|CNAME|NS|SOA|PTR):
check_dns host=google.com type=MX server=8.8.8.8
OK: google.com -> 10 smtp.google.com (1) in 9ms [ok]|'google.com_time'=9;1000;0
Query a specific DNS server (A/AAAA without server= use the system resolver; any other type or an explicit server= uses a direct DNS-over-UDP query):
check_dns host=nsclient.org type=TXT server=1.1.1.1
OK: nsclient.org -> v=spf1 include:_spf.google.com ~all (1) in 12ms [ok]
Non-recursive query against an authoritative server on a custom port:
check_dns host=example.com type=A server=192.168.10.53 port=5353 norecursion=true
OK: example.com -> 93.184.216.34 (1) in 3ms [ok]
Command-line Arguments
| Option | Default Value | Description |
|---|---|---|
| filter | Filter which marks interesting items. | |
| warning | time > 1000 | Filter which marks items which generates a warning state. |
| warn | Short alias for warning | |
| critical | result != 'ok' | Filter which marks items which generates a critical state. |
| crit | Short alias for critical. | |
| ok | Filter which marks items which generates an ok state. | |
| debug | N/A | Show debugging information in the log |
| show-all | N/A | Show details for all matches regardless of status (normally details are only showed for warnings and criticals). |
| empty-state | ignored | Return status to use when nothing matched filter. |
| perf-config | Performance data generation configuration | |
| escape-html | N/A | Escape any < and > characters to prevent HTML encoding |
| help | N/A | Show help screen (this screen) |
| help-pb | N/A | Show help screen as a protocol buffer payload |
| show-default | N/A | Show default values for a given command |
| help-short | N/A | Show help screen (short format). |
| top-syntax | ${status}: ${problem_list} | Top level syntax. |
| ok-syntax | %(status): %(list) | ok syntax. |
| empty-syntax | No DNS lookup performed | Empty syntax. |
| detail-syntax | ${host} -> ${addresses} (${count}) in ${time}ms [${result}] | Detail level syntax. |
| perf-syntax | ${host} | Performance alias syntax. |
| host | Hostname to look up. | |
| lookup | Alias for --host. | |
| type | A | DNS record type to query: A, AAAA, MX, TXT, CNAME, NS, SOA, PTR. |
| server | DNS server to query (default: the system resolver for A/AAAA, /etc/resolv.conf otherwise). | |
| port | 53 | UDP port of the DNS server. |
| norecursion | 1)] (=0 | Do not request recursion (RD=0). |
| timeout | 5000 | Timeout in milliseconds. |
| expected-address | Record that must be present in the answer (may be given multiple times). | |
| expected | Comma separated list of records that must all be present in the answer. |
filter:
Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.
warning:
Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.
Default Value: time > 1000
critical:
Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.
Default Value: result != 'ok'
ok:
Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.
empty-state:
Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.
Default Value: ignored
perf-config:
Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)
top-syntax:
Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${status}: ${problem_list}
ok-syntax:
ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).
Default Value: %(status): %(list)
empty-syntax:
Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.
Default Value: No DNS lookup performed
detail-syntax:
Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${host} -> ${addresses} (${count}) in ${time}ms [${result}]
perf-syntax:
Performance alias syntax. This is the syntax for the base names of the performance data.
Default Value: ${host}
type:
DNS record type to query: A, AAAA, MX, TXT, CNAME, NS, SOA, PTR.
Default Value: A
port:
UDP port of the DNS server.
Default Value: 53
norecursion:
Do not request recursion (RD=0).
Default Value: 1)] (=0
timeout:
Timeout in milliseconds.
Default Value: 5000
Filter keywords
| Option | Description |
|---|---|
| addresses | Comma separated list of resolved records |
| host | Hostname that was looked up |
| result | Textual result of the lookup (ok, not_found, mismatch, error, ...) |
| server | DNS server used (empty for the system resolver) |
| time | Time taken by the lookup in milliseconds |
| type | Record type that was queried (A, AAAA, MX, TXT, ...) |
Common options for all checks:
| Option | Description |
|---|---|
| count | Number of items matching the filter. |
| crit_count | Number of items matched the critical criteria. |
| crit_list | A list of all items which matched the critical criteria. |
| detail_list | A special list with critical, then warning and finally ok. |
| list | A list of all items which matched the filter. |
| ok_count | Number of items matched the ok criteria. |
| ok_list | A list of all items which matched the ok criteria. |
| problem_count | Number of items matched either warning or critical criteria. |
| problem_list | A list of all items which matched either the critical or the warning criteria. |
| status | The returned status (OK/WARN/CRIT/UNKNOWN). |
| total | Total number of items. |
| warn_count | Number of items matched the warning criteria. |
| warn_list | A list of all items which matched the warning criteria. |
check_http
Send an HTTP/HTTPS request and check the response status, time, size and body.
Jump to section:
Sample Commands
Default check against a single URL (success):
check_http url=https://nsclient.org/
L cli OK: https://nsclient.org/ -> 200 ok (68937B in 197ms)
L cli Performance data: 'https://nsclient.org/_code'=200;0;200 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=197ms;5000;0
HTTPS with explicit port and path components (page not found):
check_http protocol=https host=nsclient.org port=443 path=/no-such-page
L cli CRITICAL: https://nsclient.org:443/no-such-page -> 404 http_404 (55109B in 165ms)
L cli Performance data: 'https://nsclient.org:443/no-such-page_code'=404;0;200 'https://nsclient.org:443/no-such-page_size'=55109B;0;0 'https://nsclient.org:443/no-such-page'=165ms;5000;0
Connection / DNS failure (host does not resolve):
check_http url=https://nope.invalid/
L cli CRITICAL: https://nope.invalid/ -> 0 error: Failed to resolve nope.invalid:443: Ingen sådan värd är känd (0B in 10ms)
L cli Performance data: 'https://nope.invalid/_code'=0;0;200 'https://nope.invalid/_size'=0B;0;0 'https://nope.invalid/'=10ms;5000;0
Multiple URLs in one call:
check_http url=https://nsclient.org/ url=https://nsclient.org/nsclient/
L cli OK: https://nsclient.org/ -> 200 ok (68937B in 59ms), https://nsclient.org/nsclient/ -> 200 ok (60820B in 179ms)
L cli Performance data: 'https://nsclient.org/_code'=200;0;200 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=59ms;5000;0 'https://nsclient.org/nsclient/_code'=200;0;200 'https://nsclient.org/nsclient/_size'=60820B;0;0 'https://nsclient.org/nsclient/'=179ms;5000;0
Require an expected substring in the response body:
check_http url=https://nsclient.org/ expected-body="NSClient"
L cli OK: https://nsclient.org/ -> 200 ok (68937B in 47ms)
L cli Performance data: 'https://nsclient.org/_code'=200;0;200 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=47ms;5000;0
If the substring is absent the check goes CRITICAL with result=no_match:
check_http url=https://nsclient.org/ expected-body="this-string-is-not-present"
L cli CRITICAL: https://nsclient.org/ -> 200 no_match (68937B in 52ms)
L cli Performance data: 'https://nsclient.org/_code'=200;0;200 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=52ms;5000;0
Custom user-agent and extra headers:
check_http url=https://nsclient.org/ user-agent="nscp-monitor/1" header="X-Trace: 1"
L cli OK: https://nsclient.org/ -> 200 ok (68937B in 50ms)
L cli Performance data: 'https://nsclient.org/_code'=200;0;200 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=50ms;5000;0
Tighter latency thresholds and code rules:
check_http url=https://nsclient.org/ timeout=10000 "warn=time > 500 or code >= 400" "crit=time > 2000 or code >= 500 or result != 'ok'"
L cli OK: https://nsclient.org/ -> 200 ok (68937B in 61ms)
L cli Performance data: 'https://nsclient.org/_code'=200;400;500 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=61ms;500;2000
Custom output text (drop result if you don't want it):
check_http url=https://nsclient.org/ "top-syntax=%(status): %(list)" "detail-syntax=%(url) -> %(code) in %(time)ms"
L cli OK: https://nsclient.org/ -> 200 in 46ms
L cli Performance data: 'https://nsclient.org/_code'=200;0;200 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=46ms;5000;0
Default check via NRPE:
check_nscp_client --host 192.168.56.103 --command check_http --argument "url=https://nsclient.org/"
OK: https://nsclient.org/ -> 200 ok (68937B in 197ms)|'https://nsclient.org/_code'=200;0;200 'https://nsclient.org/_size'=68937B;0;0 'https://nsclient.org/'=197ms;5000;0
Use a specific HTTP method (HEAD, POST, PUT, …):
check_http url=https://www.google.com method=HEAD
OK: https://www.google.com -> 200 ok (0B in 58ms)|'https://www.google.com_code'=200;0;200 'https://www.google.com_size'=0B;0;0 'https://www.google.com'=58ms;5000;0
POST a body (post-data implies POST unless method= is given):
check_http url=https://httpbin.org/post post-data="name=value" content-type="application/x-www-form-urlencoded" expected-body="name"
OK: https://httpbin.org/post -> 200 ok (429B in 380ms)
HTTP Basic authentication:
check_http url=https://example.com/private username=admin password=secret
OK: https://example.com/private -> 200 ok (1200B in 88ms)
Follow redirects (default reports the 3xx as-is; onredirect=follow chases the Location):
check_http url=http://github.com onredirect=follow "detail-syntax=code=${code}"
OK: code=200
Accept a set of status codes with the code keyword, and match the body with a regex:
check_http url=https://example.com "warn=code not in (200,301,302)" "crit=code >= 500 or body not regexp 'Welcome'"
OK: https://example.com -> 200 ok (1256B in 74ms)
Alert when the TLS certificate is about to expire (ssl_expiry_days):
check_http url=https://www.google.com "warn=ssl_expiry_days < 30" "crit=ssl_expiry_days < 7" "detail-syntax=cert expires in ${ssl_expiry_days} days"
OK: cert expires in 58 days
Command-line Arguments
| Option | Default Value | Description |
|---|---|---|
| filter | Filter which marks interesting items. | |
| warning | time > 5000 | Filter which marks items which generates a warning state. |
| warn | Short alias for warning | |
| critical | code < 200 or code >= 400 or result != 'ok' | Filter which marks items which generates a critical state. |
| crit | Short alias for critical. | |
| ok | Filter which marks items which generates an ok state. | |
| debug | N/A | Show debugging information in the log |
| show-all | N/A | Show details for all matches regardless of status (normally details are only showed for warnings and criticals). |
| empty-state | ignored | Return status to use when nothing matched filter. |
| perf-config | Performance data generation configuration | |
| escape-html | N/A | Escape any < and > characters to prevent HTML encoding |
| help | N/A | Show help screen (this screen) |
| help-pb | N/A | Show help screen as a protocol buffer payload |
| show-default | N/A | Show default values for a given command |
| help-short | N/A | Show help screen (short format). |
| top-syntax | ${status}: ${problem_list} | Top level syntax. |
| ok-syntax | %(status): %(list) | ok syntax. |
| empty-syntax | No URL checked | Empty syntax. |
| detail-syntax | ${url} -> ${code} ${result} (${size}B in ${time}ms) | Detail level syntax. |
| perf-syntax | ${url} | Performance alias syntax. |
| url | Full URL to check (http://host[:port]/path or https://...). May be given multiple times. | |
| host | Hostname (used when --url is not given). | |
| port | TCP port (defaults to 80 or 443). | |
| path | / | Path component of the URL. |
| protocol | http | Protocol to use: http or https. |
| ssl | 1)] (=0 | Force https, alias for --protocol https (ssl=true). |
| timeout | 30000 | Timeout in milliseconds. |
| method | GET | HTTP method to use (GET, HEAD, POST, PUT, DELETE, ...). |
| post-data | Request body to send; implies POST unless --method is given. | |
| content-type | application/x-www-form-urlencoded | Content-Type header for the request body. |
| username | Username for HTTP Basic authentication. | |
| password | Password for HTTP Basic authentication. | |
| expected-body | Substring that must appear in the body for the check to be ok. | |
| user-agent | NSClient++ | User-Agent header value. |
| header | Additional request header in 'Name: value' form (may be given multiple times). | |
| onredirect | ok | How to handle 3xx redirects: 'follow' to follow the Location, 'ok' (default) to report the redirect as-is. |
| max-redirs | 15 | Maximum number of redirects to follow (with --onredirect follow). |
| sni | TLS Server Name Indication / verification hostname override (defaults to the URL host). | |
| tls-version | tlsv1.2+ | TLS version for https (tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.2+, tlsv1.3, sslv3). |
| verify | peer | Certificate verify mode: none, peer, peer-cert, fail-if-no-cert, fail-if-no-peer-cert, client-certificate. |
| ca | ${ca-path} | Path to a CA bundle to use when verifying the server certificate. |
| json-path | Extract a value from the JSON response body as a filter keyword: 'alias:dotted.path' (repeatable). Numeric segments index arrays; single-quote a segment containing a dot. Example: --json-path qlen:data.queue.length "crit=qlen > 100". |
filter:
Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.
warning:
Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.
Default Value: time > 5000
critical:
Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.
Default Value: code < 200 or code >= 400 or result != 'ok'
ok:
Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.
empty-state:
Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.
Default Value: ignored
perf-config:
Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)
top-syntax:
Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${status}: ${problem_list}
ok-syntax:
ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).
Default Value: %(status): %(list)
empty-syntax:
Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.
Default Value: No URL checked
detail-syntax:
Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${url} -> ${code} ${result} (${size}B in ${time}ms)
perf-syntax:
Performance alias syntax. This is the syntax for the base names of the performance data.
Default Value: ${url}
path:
Path component of the URL.
Default Value: /
protocol:
Protocol to use: http or https.
Default Value: http
ssl:
Force https, alias for --protocol https (ssl=true).
Default Value: 1)] (=0
timeout:
Timeout in milliseconds.
Default Value: 30000
method:
HTTP method to use (GET, HEAD, POST, PUT, DELETE, ...).
Default Value: GET
content-type:
Content-Type header for the request body.
Default Value: application/x-www-form-urlencoded
user-agent:
User-Agent header value.
Default Value: NSClient++
onredirect:
How to handle 3xx redirects: 'follow' to follow the Location, 'ok' (default) to report the redirect as-is.
Default Value: ok
max-redirs:
Maximum number of redirects to follow (with --onredirect follow).
Default Value: 15
tls-version:
TLS version for https (tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.2+, tlsv1.3, sslv3).
Default Value: tlsv1.2+
verify:
Certificate verify mode: none, peer, peer-cert, fail-if-no-cert, fail-if-no-peer-cert, client-certificate.
Default Value: peer
ca:
Path to a CA bundle to use when verifying the server certificate.
Default Value: ${ca-path}
Filter keywords
| Option | Description |
|---|---|
| body | Body of the response (use with substr/regex matching) |
| code | HTTP status code |
| host | Host part of the URL |
| path | Path part of the URL |
| port | TCP port that was used |
| protocol | Protocol used (http or https) |
| result | Textual result of the check (ok, error, ...) |
| size | Size of the response body in bytes |
| ssl_expiry_days | Days until the server's TLS certificate expires (-1 for plain http; negative if already expired) |
| time | Time taken by the request in milliseconds |
| url | Full URL that was requested |
Common options for all checks:
| Option | Description |
|---|---|
| count | Number of items matching the filter. |
| crit_count | Number of items matched the critical criteria. |
| crit_list | A list of all items which matched the critical criteria. |
| detail_list | A special list with critical, then warning and finally ok. |
| list | A list of all items which matched the filter. |
| ok_count | Number of items matched the ok criteria. |
| ok_list | A list of all items which matched the ok criteria. |
| problem_count | Number of items matched either warning or critical criteria. |
| problem_list | A list of all items which matched either the critical or the warning criteria. |
| status | The returned status (OK/WARN/CRIT/UNKNOWN). |
| total | Total number of items. |
| warn_count | Number of items matched the warning criteria. |
| warn_list | A list of all items which matched the warning criteria. |
check_nsclient_web_online
Query the REST API of a remote NSClient++ agent (reachability or a remote check).
About check_nsclient_web_online
check_nsclient_web_online queries the REST API of a remote NSClient++
agent over HTTPS. It has two modes:
- Reachability probe (no
command=): it hits/api/v1/infoand reports OKREST API reachable …when the agent answers, CRITICAL when it cannot be reached or authentication fails. - Remote check (
command=<check>): it runs that check on the remote agent (/api/v1/queries/<check>/commands/execute) and passes the remote Nagios status and message straight through, so the local result mirrors what the remote agent returned.
This is intended for liveness / availability monitoring of an agent from a
central host. (A fuller "run remote checks" command — check_nsclient_web — is
planned separately; this one focuses on whether the web API is online.)
Arguments:
| Argument | Description |
|---|---|
url |
Base URL of the remote agent, e.g. https://host:8443 |
host / port |
Alternative to url; port defaults to 8443 |
password |
REST API password (sent as the password header, as user admin) |
user |
Optional username → switches to HTTP Basic authentication |
command |
Remote check to run (omit for a plain reachability probe) |
argument |
Argument for the remote check; repeat for multiple |
timeout |
Request timeout in milliseconds |
tls-version |
TLS version (default tlsv1.2+) |
verify |
Certificate verify mode (default none, for self-signed agents) |
ca |
CA bundle to verify the remote certificate |
By default the remote certificate is not verified (verify=none) because
agents commonly present a self-signed certificate; set verify=peer with ca=
to enforce verification.
Jump to section:
Sample Commands
Check that a remote NSClient++ agent's REST API is reachable:
check_nsclient_web_online url=https://192.168.56.10:8443 password=secret
OK: REST API reachable on https://192.168.56.10:8443
Give host and port separately instead of a URL:
check_nsclient_web_online host=192.168.56.10 port=8443 password=secret
OK: REST API reachable on https://192.168.56.10:8443
Run a check on the remote agent and pass its result through:
check_nsclient_web_online url=https://192.168.56.10:8443 password=secret command=check_cpu
OK: CPU load is ok.
Pass arguments to the remote check (repeat argument=):
check_nsclient_web_online url=https://192.168.56.10:8443 password=secret command=check_drivesize argument=drive=/ "argument=warn=used>80%"
OK: / 42.1% used
A wrong password reports the authentication failure:
check_nsclient_web_online url=https://192.168.56.10:8443 password=wrong
CRITICAL: Authentication failed (HTTP 403) on https://192.168.56.10:8443
An unreachable agent is CRITICAL:
check_nsclient_web_online url=https://192.168.56.10:9999 password=secret
CRITICAL: Failed to reach https://192.168.56.10:9999: Connection refused
check_ntp_offset
Query an NTP server and check the offset between the local clock and the server.
Jump to section:
Sample Commands
Default check against a single NTP server:
check_ntp_offset server=pool.ntp.org
L cli OK: OK: pool.ntp.org offset=1326ms stratum=2
L cli Performance data: 'pool.ntp.org_offset'=1326;60000;120000 'pool.ntp.org_stratum'=2;16;16
Multiple servers via comma list (averaged across answers):
check_ntp_offset "servers=0.pool.ntp.org,1.pool.ntp.org,2.pool.ntp.org" timeout=2000
L cli OK: OK: 0.pool.ntp.org offset=1326ms stratum=2, 1.pool.ntp.org offset=1327ms stratum=1, 2.pool.ntp.org offset=1329ms stratum=2
L cli Performance data: '0.pool.ntp.org_offset'=1326;60000;120000 '0.pool.ntp.org_stratum'=2;16;16 '1.pool.ntp.org_offset'=1327;60000;120000 '1.pool.ntp.org_stratum'=1;16;16 '2.pool.ntp.org_offset'=1329;60000;120000 '2.pool.ntp.org_stratum'=2;16;16
Custom port and timeout:
check_ntp_offset server=time.example.com port=123 timeout=1500
check_ntp_offset server=time.example.com port=123 timeout=1500
L cli OK: OK: time.example.com offset=0ms stratum=0
L cli Performance data: 'time.example.com_offset'=0;60000;120000 'time.example.com_stratum'=0;16;16
Tighter thresholds (alert when more than 50ms / 200ms off):
check_ntp_offset server=pool.ntp.org "warn=offset > 50 or stratum >= 8" "crit=offset > 200 or stratum >= 16"
L cli CRITICAL: CRITICAL: pool.ntp.org offset=1326ms stratum=1
L cli Performance data: 'pool.ntp.org_offset'=1326;50;200 'pool.ntp.org_stratum'=1;8;16
Use signed offset to distinguish ahead vs behind:
check_ntp_offset server=pool.ntp.org "top-syntax=%(status): %(list)" "detail-syntax=%(server) signed=%(offset_signed)ms abs=%(offset)ms s=%(stratum)"
L cli OK: OK: pool.ntp.org signed=1327ms abs=1327ms s=1
L cli Performance data: 'pool.ntp.org_offset'=1327;60000;120000 'pool.ntp.org_stratum'=1;16;16
Default check via NRPE:
check_nscp_client --host 192.168.56.103 --command check_ntp_offset --argument "server=pool.ntp.org"
OK: pool.ntp.org offset=1326ms stratum=2| 'pool.ntp.org_offset'=1326;60000;120000 'pool.ntp.org_stratum'=2;16;16
Command-line Arguments
| Option | Default Value | Description |
|---|---|---|
| filter | Filter which marks interesting items. | |
| warning | offset > 50 or stratum >= 16 | Filter which marks items which generates a warning state. |
| warn | Short alias for warning | |
| critical | offset > 100 or stratum >= 16 or result != 'ok' | Filter which marks items which generates a critical state. |
| crit | Short alias for critical. | |
| ok | Filter which marks items which generates an ok state. | |
| debug | N/A | Show debugging information in the log |
| show-all | N/A | Show details for all matches regardless of status (normally details are only showed for warnings and criticals). |
| empty-state | ignored | Return status to use when nothing matched filter. |
| perf-config | Performance data generation configuration | |
| escape-html | N/A | Escape any < and > characters to prevent HTML encoding |
| help | N/A | Show help screen (this screen) |
| help-pb | N/A | Show help screen as a protocol buffer payload |
| show-default | N/A | Show default values for a given command |
| help-short | N/A | Show help screen (short format). |
| top-syntax | ${status}: ${problem_list} | Top level syntax. |
| ok-syntax | %(status): %(list) | ok syntax. |
| empty-syntax | No NTP server checked | Empty syntax. |
| detail-syntax | ${server} offset=${offset_signed}ms stratum=${stratum} | Detail level syntax. |
| perf-syntax | ${server} | Performance alias syntax. |
| server | NTP server to query (may be given multiple times). | |
| servers | Comma separated list of NTP servers to query. | |
| port | 123 | UDP port to use (default: 123). |
| timeout | 5000 | Timeout in milliseconds. |
filter:
Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.
warning:
Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.
Default Value: offset > 50 or stratum >= 16
critical:
Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.
Default Value: offset > 100 or stratum >= 16 or result != 'ok'
ok:
Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.
empty-state:
Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.
Default Value: ignored
perf-config:
Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)
top-syntax:
Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${status}: ${problem_list}
ok-syntax:
ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).
Default Value: %(status): %(list)
empty-syntax:
Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.
Default Value: No NTP server checked
detail-syntax:
Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${server} offset=${offset_signed}ms stratum=${stratum}
perf-syntax:
Performance alias syntax. This is the syntax for the base names of the performance data.
Default Value: ${server}
port:
UDP port to use (default: 123).
Default Value: 123
timeout:
Timeout in milliseconds.
Default Value: 5000
Filter keywords
| Option | Description |
|---|---|
| offset | Absolute clock offset between local host and server, in milliseconds |
| offset_signed | Signed clock offset (positive = local clock is ahead of server), in milliseconds |
| port | UDP port the query was sent to |
| result | Textual result of the query (ok, timeout, error, ...) |
| server | NTP server that was queried |
| stratum | Stratum reported by the server (0..16) |
| time | Round trip time of the NTP query in milliseconds |
Common options for all checks:
| Option | Description |
|---|---|
| count | Number of items matching the filter. |
| crit_count | Number of items matched the critical criteria. |
| crit_list | A list of all items which matched the critical criteria. |
| detail_list | A special list with critical, then warning and finally ok. |
| list | A list of all items which matched the filter. |
| ok_count | Number of items matched the ok criteria. |
| ok_list | A list of all items which matched the ok criteria. |
| problem_count | Number of items matched either warning or critical criteria. |
| problem_list | A list of all items which matched either the critical or the warning criteria. |
| status | The returned status (OK/WARN/CRIT/UNKNOWN). |
| total | Total number of items. |
| warn_count | Number of items matched the warning criteria. |
| warn_list | A list of all items which matched the warning criteria. |
check_ping
Ping another host and check the result.
Jump to section:
Sample Commands
Pinging a single host:
check_ping host=192.168.0.1
OK: All 1 hosts are ok|'192.168.0.1_loss'=0%;5;10 '192.168.0.1'=2ms;60;100
Pinging multiple hosts (repeat host=) with a total bucket:
check_ping host=1.1.1.1 host=8.8.8.8 host=google.com total
L cli OK: All 4 hosts are ok
L cli Performance data: '1.1.1.1_loss'=0%;5;10 '1.1.1.1'=3ms;60;100 '8.8.8.8_loss'=0%;5;10 '8.8.8.8'=9ms;60;100 'google.com_loss'=0%;5;10 'google.com'=2ms;60;100 'total_loss'=0%;5;10 'total'=14ms;60;100
Tighter thresholds with explicit count and timeout:
check_ping host=8.8.8.8 count=4 timeout=300 "warn=time > 30 or loss > 0%" "crit=time > 80 or loss > 25%"
L cli OK: All 1 hosts are ok
L cli Performance data: '8.8.8.8_loss'=0%;0;25 '8.8.8.8'=2ms;30;80
Custom payload and per-host text output:
check_ping host=1.1.1.1 host=8.8.8.8 payload="hello" "top-syntax=%(status): %(list)" "detail-syntax=%(host)=%(time)ms"
L cli OK: 1.1.1.1=2ms, 8.8.8.8=2ms
L cli Performance data: '1.1.1.1_loss'=0%;5;10 '1.1.1.1'=2ms;60;100 '8.8.8.8_loss'=0%;5;10 '8.8.8.8'=2ms;60;100
Default check via NRPE:
check_nscp_client --host 192.168.56.103 --command check_ping --argument "host=192.168.56.1"
OK: All 1 hosts are ok|'192.168.56.1_loss'=0%;5;10 '192.168.56.1'=1ms;60;100
Command-line Arguments
| Option | Default Value | Description |
|---|---|---|
| filter | Filter which marks interesting items. | |
| warning | time > 60 or loss > 5% | Filter which marks items which generates a warning state. |
| warn | Short alias for warning | |
| critical | time > 100 or loss > 10% | Filter which marks items which generates a critical state. |
| crit | Short alias for critical. | |
| ok | Filter which marks items which generates an ok state. | |
| debug | N/A | Show debugging information in the log |
| show-all | N/A | Show details for all matches regardless of status (normally details are only showed for warnings and criticals). |
| empty-state | unknown | Return status to use when nothing matched filter. |
| perf-config | Performance data generation configuration | |
| escape-html | N/A | Escape any < and > characters to prevent HTML encoding |
| help | N/A | Show help screen (this screen) |
| help-pb | N/A | Show help screen as a protocol buffer payload |
| show-default | N/A | Show default values for a given command |
| help-short | N/A | Show help screen (short format). |
| top-syntax | ${status}: ${ok_count}/${count} (${problem_list}) | Top level syntax. |
| ok-syntax | %(status): All %(count) hosts are ok | ok syntax. |
| empty-syntax | No hosts found | Empty syntax. |
| detail-syntax | ${ip} Packet loss = ${loss}%, RTA = ${time}ms | Detail level syntax. |
| perf-syntax | ${host} | Performance alias syntax. |
| host | The host to check (or multiple hosts). | |
| total | 1)] (=0 | Include the total of all matching hosts |
| hosts | The host to check (or multiple hosts). | |
| count | 1 | Number of packets to send. |
| timeout | 500 | Timeout in milliseconds. |
| payload | Hello from NSClient++. | The payload to send in the ping request (default: 'Hello from NSClient++') |
filter:
Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.
warning:
Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.
Default Value: time > 60 or loss > 5%
critical:
Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.
Default Value: time > 100 or loss > 10%
ok:
Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.
empty-state:
Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.
Default Value: unknown
perf-config:
Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)
top-syntax:
Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${status}: ${ok_count}/${count} (${problem_list})
ok-syntax:
ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).
Default Value: %(status): All %(count) hosts are ok
empty-syntax:
Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.
Default Value: No hosts found
detail-syntax:
Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${ip} Packet loss = ${loss}%, RTA = ${time}ms
perf-syntax:
Performance alias syntax. This is the syntax for the base names of the performance data.
Default Value: ${host}
total:
Include the total of all matching hosts
Default Value: 1)] (=0
count:
Number of packets to send.
Default Value: 1
timeout:
Timeout in milliseconds.
Default Value: 500
payload:
The payload to send in the ping request (default: 'Hello from NSClient++')
Default Value: Hello from NSClient++.
Filter keywords
| Option | Description |
|---|---|
| host | The host name or ip address (as given on command line) |
| ip | The ip address name |
| loss | Packet loss |
| recv | Number of packets received from the host |
| sent | Number of packets sent to the host |
| time | Round trip time in ms |
| timeout | Number of packets which timed out from the host |
Common options for all checks:
| Option | Description |
|---|---|
| count | Number of items matching the filter. |
| crit_count | Number of items matched the critical criteria. |
| crit_list | A list of all items which matched the critical criteria. |
| detail_list | A special list with critical, then warning and finally ok. |
| list | A list of all items which matched the filter. |
| ok_count | Number of items matched the ok criteria. |
| ok_list | A list of all items which matched the ok criteria. |
| problem_count | Number of items matched either warning or critical criteria. |
| problem_list | A list of all items which matched either the critical or the warning criteria. |
| status | The returned status (OK/WARN/CRIT/UNKNOWN). |
| total | Total number of items. |
| warn_count | Number of items matched the warning criteria. |
| warn_list | A list of all items which matched the warning criteria. |
check_ssh
Connect to an SSH port and verify the server presents a valid SSH banner.
About check_ssh
check_ssh confirms that an SSH server is reachable and presents a valid SSH
protocol banner. It connects to the port (default 22), reads the greeting
the server sends on connect, and requires it to start with SSH- (e.g.
SSH-2.0-OpenSSH_9.6). Nothing is written to the peer, so it does not initiate
a key exchange or authenticate — it is a lightweight "is sshd up and answering"
probe.
It is a thin preset over check_tcp (service=ssh), so it shares
check_tcp's keywords and thresholds:
| Keyword | Description |
|---|---|
host |
Host the check connected to |
port |
Port the check connected to (default 22) |
time |
Connection + banner-read time in milliseconds |
result |
ok, no_match, refused, timeout, resolve_failed, … |
response |
The banner the server returned |
connected |
1 when the TCP connection succeeded |
Default thresholds: warning time > 1000, critical
time > 5000 or result != 'ok'. A port that answers but is not SSH yields
result = no_match (CRITICAL); a closed port yields result = refused.
Jump to section:
Sample Commands
Check that an SSH server presents a valid banner:
check_ssh host=github.com
OK: github.com:22 ok in 13ms
L cli Performance data: 'github.com_22_time'=13;1000;5000
Non-standard SSH port:
check_ssh host=192.168.56.10 port=2222
OK: 192.168.56.10:2222 ok in 2ms
A port that is not speaking SSH is CRITICAL (no_match):
check_ssh host=www.google.com port=443
CRITICAL: www.google.com:443 no_match in 12ms
Tighter response-time thresholds:
check_ssh host=192.168.56.10 "warn=time > 200" "crit=time > 1000 or result != 'ok'"
OK: 192.168.56.10:22 ok in 3ms
Check via NRPE:
check_nscp_client --host 192.168.56.103 --command check_ssh --argument "host=192.168.56.10"
OK: 192.168.56.10:22 ok in 2ms
Command-line Arguments
| Option | Default Value | Description |
|---|---|---|
| filter | Filter which marks interesting items. | |
| warning | time > 1000 | Filter which marks items which generates a warning state. |
| warn | Short alias for warning | |
| critical | time > 5000 or result != 'ok' | Filter which marks items which generates a critical state. |
| crit | Short alias for critical. | |
| ok | Filter which marks items which generates an ok state. | |
| debug | N/A | Show debugging information in the log |
| show-all | N/A | Show details for all matches regardless of status (normally details are only showed for warnings and criticals). |
| empty-state | ignored | Return status to use when nothing matched filter. |
| perf-config | Performance data generation configuration | |
| escape-html | N/A | Escape any < and > characters to prevent HTML encoding |
| help | N/A | Show help screen (this screen) |
| help-pb | N/A | Show help screen as a protocol buffer payload |
| show-default | N/A | Show default values for a given command |
| help-short | N/A | Show help screen (short format). |
| top-syntax | ${status}: ${problem_list} | Top level syntax. |
| ok-syntax | %(status): %(list) | ok syntax. |
| empty-syntax | No hosts checked | Empty syntax. |
| detail-syntax | ${host}:${port} ${result} in ${time}ms | Detail level syntax. |
| perf-syntax | ${host}_${port} | Performance alias syntax. |
| host | Host(s) to connect to (may be given multiple times). | |
| hosts | Comma separated list of hosts to connect to. | |
| port | TCP port to connect to. | |
| timeout | 5000 | Connection / read timeout in milliseconds. |
| send | Optional payload to send after the connection is established. | |
| expect | Optional substring expected in the response. | |
| ssl | 1)] (=0 | Wrap the connection in TLS/SSL after connecting (ssl=true). |
| tls-version | tlsv1.2+ | TLS version when --ssl is used (tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.2+, tlsv1.3, sslv3). |
| verify | none | Certificate verify mode when --ssl is used: none (default), peer, ... (peer requires --ca). |
| ca | CA bundle used to verify the server certificate when --ssl --verify peer is used. |
filter:
Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.
warning:
Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.
Default Value: time > 1000
critical:
Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.
Default Value: time > 5000 or result != 'ok'
ok:
Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.
empty-state:
Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.
Default Value: ignored
perf-config:
Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)
top-syntax:
Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${status}: ${problem_list}
ok-syntax:
ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).
Default Value: %(status): %(list)
empty-syntax:
Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.
Default Value: No hosts checked
detail-syntax:
Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${host}:${port} ${result} in ${time}ms
perf-syntax:
Performance alias syntax. This is the syntax for the base names of the performance data.
Default Value: ${host}_${port}
timeout:
Connection / read timeout in milliseconds.
Default Value: 5000
ssl:
Wrap the connection in TLS/SSL after connecting (ssl=true).
Default Value: 1)] (=0
tls-version:
TLS version when --ssl is used (tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.2+, tlsv1.3, sslv3).
Default Value: tlsv1.2+
verify:
Certificate verify mode when --ssl is used: none (default), peer, ... (peer requires --ca).
Default Value: none
Filter keywords
| Option | Description |
|---|---|
| connected | 1 when the connection succeeded, 0 otherwise |
| host | Host the check connected to |
| port | TCP port the check connected to |
| response | The data received from the peer (use with 'like'/'regexp' for custom matching) |
| result | Textual result of the check (ok, refused, timeout, no_match, ...) |
| time | Connection time in milliseconds |
Common options for all checks:
| Option | Description |
|---|---|
| count | Number of items matching the filter. |
| crit_count | Number of items matched the critical criteria. |
| crit_list | A list of all items which matched the critical criteria. |
| detail_list | A special list with critical, then warning and finally ok. |
| list | A list of all items which matched the filter. |
| ok_count | Number of items matched the ok criteria. |
| ok_list | A list of all items which matched the ok criteria. |
| problem_count | Number of items matched either warning or critical criteria. |
| problem_list | A list of all items which matched either the critical or the warning criteria. |
| status | The returned status (OK/WARN/CRIT/UNKNOWN). |
| total | Total number of items. |
| warn_count | Number of items matched the warning criteria. |
| warn_list | A list of all items which matched the warning criteria. |
check_tcp
Connect to a TCP port and optionally send/expect data to check that a service is reachable.
Jump to section:
Sample Commands
Default check against a single host/port:
check_tcp host=127.0.0.1 port=8443
L cli OK: OK: 127.0.0.1:8443 ok in 0ms
L cli Performance data: '127.0.0.1_8443_time'=0;1000;5000
Multiple hosts via comma list:
check_tcp host=www.google.com host=www.ibm.com port=443 timeout=2000
L cli OK: OK: www.google.com:443 ok in 11ms, www.ibm.com:443 ok in 9ms
L cli Performance data: 'www.google.com_443_time'=11;1000;5000 'www.ibm.com_443_time'=9;1000;5000
Send a payload and require an expected substring in the response:
check_tcp host=smtp.gmail.com port=25 send="EHLO nsclient.org" expect="250"
L cli CRITICAL: CRITICAL: smtp.gmail.com:25 no_match in 25ms
L cli Performance data: 'smtp.gmail.com_25_time'=25;1000;5000
Tighter thresholds:
check_tcp host=www.google.com port=443 "warn=time > 100" "crit=time > 500 or connected = 0"
L cli OK: OK: www.google.com:443 ok in 11ms
L cli Performance data: 'www.google.com_443_connected'=1;0;0 'www.google.com_443_time'=11;100;500
Show every host explicitly:
check_tcp host=a.example.com host=b.example.com port=80 "top-syntax=%(status): %(list)" "detail-syntax=%(host):%(port)=%(result) in %(time)ms"
OK: a.example.com:80=ok in 14ms, b.example.com:80=ok in 19ms
Use a service preset (ftp, pop, imap, smtp, ssh) — sets the port, greeting and expected-response regex:
check_tcp host=mail.example.com service=smtp
OK: mail.example.com:25 ok in 8ms
Wrap the connection in TLS with ssl=true (e.g. to test an HTTPS listener answers):
check_tcp host=www.google.com port=443 ssl=true
OK: www.google.com:443 ok in 11ms|'www.google.com_443_time'=11;1000;5000
Implicit-TLS service presets (spop, simap, ssmtp) connect over TLS and check the greeting:
check_tcp host=smtp.gmail.com service=ssmtp
OK: smtp.gmail.com:465 ok in 16ms|'smtp.gmail.com_465_time'=16;1000;5000
Match the peer's response with a regex via the response keyword:
check_tcp host=mail.example.com port=25 "crit=response not regexp '^220'"
OK: mail.example.com:25 ok in 8ms
Verify the server certificate when using TLS (needs a CA bundle):
check_tcp host=secure.example.com port=443 ssl=true verify=peer ca=/etc/ssl/certs/ca-certificates.crt
OK: secure.example.com:443 ok in 21ms
Default check via NRPE:
check_nscp_client --host 192.168.56.103 --command check_tcp --argument "host=192.168.56.1" --argument "port=22"
OK: All 1 hosts are ok|'192.168.56.1_22 time'=2ms;1000;5000
Command-line Arguments
| Option | Default Value | Description |
|---|---|---|
| filter | Filter which marks interesting items. | |
| warning | time > 1000 | Filter which marks items which generates a warning state. |
| warn | Short alias for warning | |
| critical | time > 5000 or result != 'ok' | Filter which marks items which generates a critical state. |
| crit | Short alias for critical. | |
| ok | Filter which marks items which generates an ok state. | |
| debug | N/A | Show debugging information in the log |
| show-all | N/A | Show details for all matches regardless of status (normally details are only showed for warnings and criticals). |
| empty-state | ignored | Return status to use when nothing matched filter. |
| perf-config | Performance data generation configuration | |
| escape-html | N/A | Escape any < and > characters to prevent HTML encoding |
| help | N/A | Show help screen (this screen) |
| help-pb | N/A | Show help screen as a protocol buffer payload |
| show-default | N/A | Show default values for a given command |
| help-short | N/A | Show help screen (short format). |
| top-syntax | ${status}: ${problem_list} | Top level syntax. |
| ok-syntax | %(status): %(list) | ok syntax. |
| empty-syntax | No hosts checked | Empty syntax. |
| detail-syntax | ${host}:${port} ${result} in ${time}ms | Detail level syntax. |
| perf-syntax | ${host}_${port} | Performance alias syntax. |
| host | Host(s) to connect to (may be given multiple times). | |
| hosts | Comma separated list of hosts to connect to. | |
| port | TCP port to connect to. | |
| timeout | 5000 | Connection / read timeout in milliseconds. |
| send | Optional payload to send after the connection is established. | |
| expect | Optional substring expected in the response. | |
| ssl | 1)] (=0 | Wrap the connection in TLS/SSL after connecting (ssl=true). |
| tls-version | tlsv1.2+ | TLS version when --ssl is used (tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.2+, tlsv1.3, sslv3). |
| verify | none | Certificate verify mode when --ssl is used: none (default), peer, ... (peer requires --ca). |
| ca | CA bundle used to verify the server certificate when --ssl --verify peer is used. | |
| service | Service preset (ftp, pop, imap, smtp, ssh, spop, simap, ssmtp): sets a default port, greeting and expected-response regex. The s-prefixed variants use implicit TLS. |
filter:
Filter which marks interesting items. Interesting items are items which will be included in the check. They do not denote warning or critical state instead it defines which items are relevant and you can remove unwanted items.
warning:
Filter which marks items which generates a warning state. If anything matches this filter the return status will be escalated to warning.
Default Value: time > 1000
critical:
Filter which marks items which generates a critical state. If anything matches this filter the return status will be escalated to critical.
Default Value: time > 5000 or result != 'ok'
ok:
Filter which marks items which generates an ok state. If anything matches this any previous state for this item will be reset to ok.
empty-state:
Return status to use when nothing matched filter. If no filter is specified this will never happen unless the file is empty.
Default Value: ignored
perf-config:
Performance data generation configuration TODO: obj ( key: value; key: value) obj (key:valuer;key:value)
top-syntax:
Top level syntax. Used to format the message to return can include text as well as special keywords which will include information from the checks. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${status}: ${problem_list}
ok-syntax:
ok syntax. DEPRECATED! This is the syntax for when an ok result is returned. This value will not be used if your syntax contains %(list) or %(count).
Default Value: %(status): %(list)
empty-syntax:
Empty syntax. DEPRECATED! This is the syntax for when nothing matches the filter.
Default Value: No hosts checked
detail-syntax:
Detail level syntax. Used to format each resulting item in the message. %(list) will be replaced with all the items formated by this syntax string in the top-syntax. To add a keyword to the message you can use two syntaxes either ${keyword} or %(keyword) (there is no difference between them apart from ${} can be difficult to escape on linux).
Default Value: ${host}:${port} ${result} in ${time}ms
perf-syntax:
Performance alias syntax. This is the syntax for the base names of the performance data.
Default Value: ${host}_${port}
timeout:
Connection / read timeout in milliseconds.
Default Value: 5000
ssl:
Wrap the connection in TLS/SSL after connecting (ssl=true).
Default Value: 1)] (=0
tls-version:
TLS version when --ssl is used (tlsv1.0, tlsv1.1, tlsv1.2, tlsv1.2+, tlsv1.3, sslv3).
Default Value: tlsv1.2+
verify:
Certificate verify mode when --ssl is used: none (default), peer, ... (peer requires --ca).
Default Value: none
Filter keywords
| Option | Description |
|---|---|
| connected | 1 when the connection succeeded, 0 otherwise |
| host | Host the check connected to |
| port | TCP port the check connected to |
| response | The data received from the peer (use with 'like'/'regexp' for custom matching) |
| result | Textual result of the check (ok, refused, timeout, no_match, ...) |
| time | Connection time in milliseconds |
Common options for all checks:
| Option | Description |
|---|---|
| count | Number of items matching the filter. |
| crit_count | Number of items matched the critical criteria. |
| crit_list | A list of all items which matched the critical criteria. |
| detail_list | A special list with critical, then warning and finally ok. |
| list | A list of all items which matched the filter. |
| ok_count | Number of items matched the ok criteria. |
| ok_list | A list of all items which matched the ok criteria. |
| problem_count | Number of items matched either warning or critical criteria. |
| problem_list | A list of all items which matched either the critical or the warning criteria. |
| status | The returned status (OK/WARN/CRIT/UNKNOWN). |
| total | Total number of items. |
| warn_count | Number of items matched the warning criteria. |
| warn_list | A list of all items which matched the warning criteria. |