Subagent:PortCheck - Revision history

AlexKirhenshtein: Text replacement - "^" to "{{deprecated}}"

2022-09-13T16:13:53Z

Text replacement - "^" to "{{deprecated}}"

← Older revision		Revision as of 16:13, 13 September 2022
Line 1:		Line 1:
	Information moved to documentation:		{{deprecated}}Information moved to documentation:

	https://www.netxms.org/documentation/adminguide/service-monitoring.html?highlight=portcheck#portcheck-configuration		https://www.netxms.org/documentation/adminguide/service-monitoring.html?highlight=portcheck#portcheck-configuration

TatjanaDubrovica: Replaced content with "Information moved to documentation: https://www.netxms.org/documentation/adminguide/service-monitoring.html?highlight=portcheck#portcheck-configuration"

2017-11-24T14:58:44Z

Replaced content with "Information moved to documentation: https://www.netxms.org/documentation/adminguide/service-monitoring.html?highlight=portcheck#portcheck-configuration"

← Older revision		Revision as of 14:58, 24 November 2017
Line 1:		Line 1:
	~~{{DISPLAYTITLE~~:~~PortCheck Subagent}}~~		Information moved to documentation:
	~~This subagent can be used to check TCP ports and specifically implements checks for common services.~~

			https://www.netxms.org/documentation/adminguide/service-monitoring.html?highlight=portcheck#portcheck-configuration
	~~= Provided Parameters =~~

	~~When loaded, PORTCHECK subagent adds the following parameters to agent:~~

	~~ServiceCheck.* parameters:~~
	~~{\| class="wikitable" style="width: 70%"~~
	\|-
	~~! Parameter !! Description~~
	\|-
	\| ServiceCheck.Custom(''target'',''port''[,''timeout'']) \|\| Check that TCP ''port'' is open on ''target''. Optional argument ''timeout'' specifies timeout in milliseconds. This is a very simple test that does nothing more than check the port is open.
	\|-
	\| ServiceCheck.HTTP(''target'',[''port''],''URI'',''hostHeader''[,''regex''[,''timeout'']]) \|\| Check that HTTP service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 80 will be used. The ''URI'' is NOT a URL it is the host header request URI. As an example to test URL http://www.netxms.org/~~index.html enter www.netxms.org:~~/index.html. ''hostHeader'' is currently not used, but may be the Host option at some point in the request made. Optional argument ''regex'' is the regular expression to check returned from the request, otherwise "^HTTP/~~1.[01] 200 .*" will be used. Optional argument ''timeout'' specifies timeout in milliseconds.~~
	\|-
	~~\| ServiceCheck.HTTPS(''target'',[''port''],''URI'',''hostHeader''[,''regex''[,''timeout'']]) \|\| Check that HTTPS service is running on ''target''. Arguments are the same as for ServiceCheck.HTTP(*)~~
	\|-
	~~\| ServiceCheck.POP3(''target'',''username'',''password''[,''timeout'') \|\| Check that POP3~~ service ~~is running on ''target'' and that we are able to login using the supplied ''username'' and ''password''. Optional argument ''timeout'' specifies timeout in milliseconds.~~
	\|-
	~~\| ServiceCheck~~.SMTP(''target'',''toAddress''[,''timeout'']) \|\| Check that SMTP service is running on ''target'' and that it will accept an e-mail to ''toAddress''. The e-mail will be from noreply@''DomainName'' using the ''DomainName'' option in the config file or its default value (see below). Optional argument ''timeout'' specifies timeout in milliseconds.
	\|-
	\| ServiceCheck.SSH(''target''[,''port''[,''timeout]]) \|\| Check that SSH service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 22 will be used. Optional argument ''timeout'' specifies timeout in milliseconds.
	\|-
	\| ServiceCheck.Telnet(''target''[,''port''[,''timeout]]) \|\| Check that Telnet service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 23 will be used. Optional argument ''timeout'' specifies timeout in milliseconds.
	\|}

	~~ServiceResponseTime.* parameters:~~
	~~{\| class~~=~~"wikitable" style="width: 70%"~~
	\|-
	~~! Parameter !! Description~~
	\|-
	~~\| ServiceResponseTime.Custom(''target'',''port''[,''timeout'']) \|\| Same as ServiceCheck.Custom(*), but returned value is the response time of the service. See Response Codes table below.~~
	\|-
	\| ServiceResponseTime.HTTP(''target'',[''port''],''URI'',''hostHeader''[,''regex''[,''timeout'']]) \|\| Same as ServiceCheck.HTTP(*), but returned value is the response time of the service. See Response Codes table below.
	\|-
	\| ServiceResponseTime.HTTPS(''target'',[''port''],''URI'',''hostHeader''[,''regex''[,''timeout'']]) \|\| Same as ServiceCheck.HTTPS(*), but returned value is the response time of the service. See Response Codes table below.
	\|-
	~~\| ServiceResponseTime.POP3(''target'',''username'',''password''[,''timeout'') \|\| Same as ServiceCheck.POP3(*), but returned value is the response time of the service. See Response Codes table below.~~
	\|-
	~~\| ServiceResponseTime.SMTP(''target'',''toAddress''[,''timeout'']) \|\| Same as ServiceCheck.SMTP(*), but returned value is the response time of the service. See Response Codes table below.~~
	\|-
	~~\| ServiceResponseTime.SSH(''target''[,''port''[,''timeout]]) \|\| Same as ServiceCheck.SSH(*), but returned value is the response time of the service. See Response Codes table below.~~
	\|-
	~~\| ServiceResponseTime.Telnet(''target''[,''port''[,''timeout]]) \|\| Same as ServiceCheck.Telnet(*), but returned value is the response time of the service. See Response Codes table below.~~
	\|}

	~~= Response Codes =~~
	~~===ServiceCheck.*===~~

	~~All of the ServiceCheck.* parameters return the following values:~~

	~~{\| class="wikitable" style="width: 70%"~~
	\|-
	~~! Value !! Description~~
	\|-
	~~\| 0 \|\| Success, ''target'' was connected to an returned expected response.~~
	\|-
	~~\| 1 \|\| Invalid arguments were passed.~~
	\|-
	~~\| 2 \|\| Cannot connect to ''target''.~~
	\|-
	~~\| 3 \|\| Invalid / Unexpected response from ''target''.~~
	\|}

	~~===ServiceResponseTime.*===~~
	~~'''Before 2.0.2'''~~

	~~All of the ServiceResponseTime.* parameters return the actual response time, up to timeout.<br>~~
	~~If return value = timeout value, this means the service was unreachable.~~

	Please note there was a bug for versions older than 2.0.2, where ServiceResponseTime.* would return response codes from ServiceCheck.* (1 for invalid arguments, 2 for "Cannot connect", etc.) incorrectly as the response time of the service.<br>
	~~This means that you would see very low response time (1,2,3), even tho the check never happened, as the returned value was actually an error.~~

	~~'''After 2.0.2'''~~

	~~All of the ServiceResponseTime.* parameters return the actual response time (if a resonse was received).<br>~~
	~~If there was a timeout, or if invalid response was received, or if provided arguments were invalid, the parameter will return a data collection error <<ERROR>>.~~

	~~= Configuration file =~~

	~~All~~ configuration ~~parameters related to PORTCHECK subagent should be placed into '''*PORTCHECK''' section of agent's configuration file. The following configuration parameters are supported:~~

	~~{\| class="wikitable"~~
	\|-
	~~! Parameter !! Format !! Description !! Default value~~
	\|-
	~~\| DomainName \|\| ''string'' \|\| Set default domain name for processing. Currently this is only used by SMTP check to set the from e-mail address. \|\| netxms.org~~
	\|-
	~~\| Timeout \|\| ''milliseconds'' \|\| Set response timeout to ''milliseconds''. \|\| 3000~~
	\|}

	~~== Configuration Example ==~~

	~~<syntaxhighlight lang="ini">~~
	~~# This sample nxagentd.conf instructs agent to:~~
	~~# 1. Load PORTCHECK subagent~~
	~~# 2. Set domain name for from e-mail to netxms.demo~~
	~~# 3. Default timeout for commands set to 5 seconds (5000 milliseconds)~~

	~~MasterServers = netxms.demo~~
	~~SubAgent = /usr/lib/libnsm_portcheck.so~~

	*portCheck
	~~DomainName = netxms.demo~~
	~~Timeout = 5000~~

	~~</syntaxhighlight>~~

Tomas Kirnak: Clarified ServiceResponseTime.* behavior before 2.0.2

2016-01-17T17:28:55Z

Clarified ServiceResponseTime.* behavior before 2.0.2

← Older revision		Revision as of 17:28, 17 January 2016
Line 71:		Line 71:
	If return value = timeout value, this means the service was unreachable.		If return value = timeout value, this means the service was unreachable.

	Please ~~not~~ there was a bug for versions older than 2.0.2, where ~~if you provided invalid parameters,~~ ServiceResponseTime.* would return a very low ~~return value~~, ~~altho~~ the check never actually ~~happened due to incorrect parameters~~.		Please note there was a bug for versions older than 2.0.2, where ServiceResponseTime.* would return response codes from ServiceCheck.* (1 for invalid arguments, 2 for "Cannot connect", etc.) incorrectly as the response time of the service.<br>
			This means that you would see very low response time (1,2,3), even tho the check never happened, as the returned value was actually an error.

	'''After 2.0.2'''		'''After 2.0.2'''

Tomas Kirnak: Clarified ServiceResponseTime.* return values

2016-01-17T17:21:06Z

Clarified ServiceResponseTime.* return values

← Older revision		Revision as of 17:21, 17 January 2016
Line 48:		Line 48:

	= Response Codes =		= Response Codes =
			===ServiceCheck.*===

	All of the ServiceCheck.* parameters return the following values:		All of the ServiceCheck.* parameters return the following values:

Line 62:		Line 64:
	\| 3 \|\| Invalid / Unexpected response from ''target''.		\| 3 \|\| Invalid / Unexpected response from ''target''.
	\|}		\|}

			===ServiceResponseTime.*===
			'''Before 2.0.2'''

	All of the ServiceResponseTime.* parameters return the actual response time, up to timeout.<br>		All of the ServiceResponseTime.* parameters return the actual response time, up to timeout.<br>
	If return value = timeout value, this means the service was unreachable.		If return value = timeout value, this means the service was unreachable.

			Please not there was a bug for versions older than 2.0.2, where if you provided invalid parameters, ServiceResponseTime.* would return a very low return value, altho the check never actually happened due to incorrect parameters.

			'''After 2.0.2'''

			All of the ServiceResponseTime.* parameters return the actual response time (if a resonse was received).<br>
			If there was a timeout, or if invalid response was received, or if provided arguments were invalid, the parameter will return a data collection error <<ERROR>>.

	= Configuration file =		= Configuration file =

Tomas Kirnak: Improved formatting, fixed errors.

2016-01-16T10:29:42Z

Improved formatting, fixed errors.

← Older revision		Revision as of 10:29, 16 January 2016
Line 7:		Line 7:
	When loaded, PORTCHECK subagent adds the following parameters to agent:		When loaded, PORTCHECK subagent adds the following parameters to agent:

			ServiceCheck.* parameters:
	{\| class="wikitable" style="width: 70%"		{\| class="wikitable" style="width: 70%"
	\|-		\|-
Line 24:		Line 25:
	\|-		\|-
	\| ServiceCheck.Telnet(''target''[,''port''[,''timeout]]) \|\| Check that Telnet service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 23 will be used. Optional argument ''timeout'' specifies timeout in milliseconds.		\| ServiceCheck.Telnet(''target''[,''port''[,''timeout]]) \|\| Check that Telnet service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 23 will be used. Optional argument ''timeout'' specifies timeout in milliseconds.
			\|}

			ServiceResponseTime.* parameters:
			{\| class="wikitable" style="width: 70%"
			\|-
			! Parameter !! Description
	\|-		\|-
	\| ServiceResponseTime.Custom(''target'',''port''[,''timeout'']) \|\| Same as ServiceCheck.Custom(*), but returned value is the response time of the service. See Response Codes table below.		\| ServiceResponseTime.Custom(''target'',''port''[,''timeout'']) \|\| Same as ServiceCheck.Custom(*), but returned value is the response time of the service. See Response Codes table below.
Line 56:		Line 63:
	\|}		\|}

	All of the ServiceResponseTime.* parameters return the actual response time, up to ~~uptime~~.<br>		All of the ServiceResponseTime.* parameters return the actual response time, up to timeout.<br>
	If return value = timeout value, this means the service was unreachable.		If return value = timeout value, this means the service was unreachable.

Tomas Kirnak at 10:27, 16 January 2016

2016-01-16T10:27:29Z

@@ Line 14: / Line 14: @@
 |-
 | ServiceCheck.HTTP(''target'',[''port''],''URI'',''hostHeader''[,''regex''[,''timeout'']]) || Check that HTTP service is running on ''target''.  Optional argument ''port'' specifies the port to connect with, otherwise 80 will be used.  The ''URI'' is NOT a URL it is the host header request URI.  As an example to test URL http://www.netxms.org/index.html enter www.netxms.org:/index.html. ''hostHeader'' is currently not used, but may be the Host option at some point in the request made.  Optional argument ''regex'' is the regular expression to check returned from the request, otherwise "^HTTP/1.[01] 200 .*" will be used.  Optional argument ''timeout'' specifies timeout in milliseconds.
 |-
 | ServiceCheck.POP3(''target'',''username'',''password''[,''timeout'') || Check that POP3 service is running on ''target'' and that we are able to login using the supplied ''username'' and ''password''.  Optional argument ''timeout'' specifies timeout in milliseconds.
@@ Line 22: / Line 24: @@
 |-
 | ServiceCheck.Telnet(''target''[,''port''[,''timeout]]) || Check that Telnet service is running on ''target''.  Optional argument ''port'' specifies the port to connect with, otherwise 23 will be used.  Optional argument ''timeout'' specifies timeout in milliseconds.
 |}
@@ Line 39: / Line 55: @@
 | 3 || Invalid / Unexpected response from ''target''.
 |}
 = Configuration file =

Lweidig: Initial version

2012-08-16T16:25:16Z

Initial version

← Older revision		Revision as of 16:25, 16 August 2012
Line 13:		Line 13:
	\| ServiceCheck.Custom(''target'',''port''[,''timeout'']) \|\| Check that TCP ''port'' is open on ''target''. Optional argument ''timeout'' specifies timeout in milliseconds. This is a very simple test that does nothing more than check the port is open.		\| ServiceCheck.Custom(''target'',''port''[,''timeout'']) \|\| Check that TCP ''port'' is open on ''target''. Optional argument ''timeout'' specifies timeout in milliseconds. This is a very simple test that does nothing more than check the port is open.
	\|-		\|-
	\| ServiceCheck.HTTP(''target'',[''port''],''URI'',''hostHeader'',''regex''[,''timeout'']) \|\|		\| ServiceCheck.HTTP(''target'',[''port''],''URI'',''hostHeader''[,''regex''[,''timeout'']]) \|\| Check that HTTP service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 80 will be used. The ''URI'' is NOT a URL it is the host header request URI. As an example to test URL http://www.netxms.org/index.html enter www.netxms.org:/index.html. ''hostHeader'' is currently not used, but may be the Host option at some point in the request made. Optional argument ''regex'' is the regular expression to check returned from the request, otherwise "^HTTP/1.[01] 200 .*" will be used. Optional argument ''timeout'' specifies timeout in milliseconds.
	\|-		\|-
	\| ServiceCheck.POP3(''target'',''username'',''password''[,''timeout'') \|\| Check that POP3 service is running on ''target'' and that we are able to login using the supplied ''username'' and ''password''. Optional argument ''timeout'' specifies timeout in milliseconds.		\| ServiceCheck.POP3(''target'',''username'',''password''[,''timeout'') \|\| Check that POP3 service is running on ''target'' and that we are able to login using the supplied ''username'' and ''password''. Optional argument ''timeout'' specifies timeout in milliseconds.

Lweidig: Initial version - HTTP, just want to save this.

2012-08-16T16:14:06Z

Initial version - HTTP, just want to save this.

New page

{{DISPLAYTITLE:PortCheck Subagent}}
This subagent can be used to check TCP ports and specifically implements checks for common services.

= Provided Parameters =

When loaded, PORTCHECK subagent adds the following parameters to agent:

{| class="wikitable" style="width: 70%"
|-
! Parameter !! Description
|-
| ServiceCheck.Custom(''target'',''port''[,''timeout'']) || Check that TCP ''port'' is open on ''target''. Optional argument ''timeout'' specifies timeout in milliseconds. This is a very simple test that does nothing more than check the port is open.
|-
| ServiceCheck.HTTP(''target'',[''port''],''URI'',''hostHeader'',''regex''[,''timeout'']) ||
|-
| ServiceCheck.POP3(''target'',''username'',''password''[,''timeout'') || Check that POP3 service is running on ''target'' and that we are able to login using the supplied ''username'' and ''password''. Optional argument ''timeout'' specifies timeout in milliseconds.
|-
| ServiceCheck.SMTP(''target'',''toAddress''[,''timeout'']) || Check that SMTP service is running on ''target'' and that it will accept an e-mail to ''toAddress''. The e-mail will be from noreply@''DomainName'' using the ''DomainName'' option in the config file or its default value (see below). Optional argument ''timeout'' specifies timeout in milliseconds.
|-
| ServiceCheck.SSH(''target''[,''port''[,''timeout]]) || Check that SSH service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 22 will be used. Optional argument ''timeout'' specifies timeout in milliseconds.
|-
| ServiceCheck.Telnet(''target''[,''port''[,''timeout]]) || Check that Telnet service is running on ''target''. Optional argument ''port'' specifies the port to connect with, otherwise 23 will be used. Optional argument ''timeout'' specifies timeout in milliseconds.
|}

= Response Codes =
All of the ServiceCheck.* parameters return the following values:

{| class="wikitable" style="width: 70%"
|-
! Value !! Description
|-
| 0 || Success, ''target'' was connected to an returned expected response.
|-
| 1 || Invalid arguments were passed.
|-
| 2 || Cannot connect to ''target''.
|-
| 3 || Invalid / Unexpected response from ''target''.
|}

= Configuration file =

All configuration parameters related to PORTCHECK subagent should be placed into '''*PORTCHECK''' section of agent's configuration file. The following configuration parameters are supported:

{| class="wikitable"
|-
! Parameter !! Format !! Description !! Default value
|-
| DomainName || ''string'' || Set default domain name for processing. Currently this is only used by SMTP check to set the from e-mail address. || netxms.org
|-
| Timeout || ''milliseconds'' || Set response timeout to ''milliseconds''. || 3000
|}

== Configuration Example ==

<syntaxhighlight lang="ini">
# This sample nxagentd.conf instructs agent to:
# 1. Load PORTCHECK subagent
# 2. Set domain name for from e-mail to netxms.demo
# 3. Default timeout for commands set to 5 seconds (5000 milliseconds)

MasterServers = netxms.demo
SubAgent = /usr/lib/libnsm_portcheck.so

*portCheck
DomainName = netxms.demo
Timeout = 5000

</syntaxhighlight>