A pimatic plugin to probe HTTP(S) and TCP services.

Contributions to the project are welcome. You can simply fork the project and create a pull request with your contribution to start with. If you like this plugin, please consider ★ starring the project on github.

Note, instead of editing config.json as suggested in the remainder it is easier to use the plugin and device configuration editors provided as part of the web frontend for pimatic 0.9.

You can load the plugin by editing your config.json to include the following in the plugins section. For debugging purposes you may set property debug to true. This will write additional debug messages to the pimatic log.

{
      "plugin": "probe",
      "debug": false
}

Then you need to add a device in the devices section. Currently, the following device types are supported:

• HttpProbe: This type provides a probe for HTTP/HTTPS services by sending a HTTP GET request and checking the response.
• TcpConnectProbe: This type provides a probe for TCP-based services by establishing a TCP connection and testing the connection status.

As part of the device definition you need to provide the url for the Web Service to be probed. Note, the URL may also contain a port number and path if needed, for example: "http://fritz.box:88/details.html". If the property enableResponseTime is set to true (false by default) the device will additionally expose a responseTime attribute, which allows for monitoring the response times. You may also set the interval property to specify the probing interval in seconds (60 seconds by default). Warning Notice: Generally, it is not advised to ping external services at a high frequency as this may be regarded as a denial-of-service attack!

{
      "id": "probel",
      "class": "HttpProbe",
      "name": "Router Web Page",
      "url": "http://fritz.box",
      "enableResponseTime": false,
      "interval": 60
}

This section is for advanced users with a good understanding of the HTTP protocol.

By default, HttpProbe accepts responses with any HTTP status code. This may not be satisfactory as this way you will not be able to detect HTTP-specific errors, such as 404 (Not Found) or 502 (Bad Gateway). If you require a specific accept pattern you can set the property acceptedStatusCodes which holds an array of accepted status codes. The value 0 is provided to allow all status codes by default.

{
    "id": "probe2",
    "class": "HttpProbe",
    "name": "Router Web Page with Basic Auth",
    "url": "http://fritz.box",
    "enableResponseTime": false,
    "interval": 60,
    "acceptedStatusCodes": [
        200
    ],
    "maxRedirects": 0
}

By default, HttpProbe accepts responses with any HTTP status code which includes code 401 (Unauthorized). However, you can perform proper authentication by setting the properties username and password. In this case you also need to remove status code 401 from the list of accepted status codes by setting the acceptedStatusCodes property. See example below. Warning Notice: Do not set username and password as part of the URL as this has been deprecated and it presents a security risk!

{
    "id": "probe3",
    "class": "HttpProbe",
    "name": "Router Web Page with Basic Auth",
    "url": "http://fritz.box",
    "enableResponseTime": false,
    "interval": 60
    "username": "foo",
    "password": "bar",
    "acceptedStatusCodes": [
        200
    ]
}

By default, HttpProbe does not verify the server certificate if connected to a HTTPS server. The verification can be enabled by setting the verifyPeerCert property to true. In this case, HttpProbe will fail (absent state) if the server certificate cannot be verified.

{
    "id": "probe4",
    "class": "HttpProbe",
    "name": "Router Web Page with Basic Auth",
    "url": "https://fritz.box",
    "verifyPeerCert": true,
    "enableResponseTime": false,
    "interval": 60
    "username": "foo",
    "password": "bar",
    "acceptedStatusCodes": [
        200
    ]
}

By default, HttpProbe will follow up to 5 redirects automatically. You can change the maximum number of redirects followed automatically by setting the property maxRedirects. If you set the maxRedirects to 0, redirects will not be followed automatically.

{
    "id": "probe5",
    "class": "HttpProbe",
    "name": "Router Web Page with Redirect",
    "url": "http://fritz.box",
    "enableResponseTime": false,
    "interval": 60,
    "maxRedirects": 0
}

If you wish to hide the sparkline (the mini-graph) of responseTime attribute display this is possible with pimatic v0.8.68 and higher using the xAttributeOptions property as shown in the following example. Using the xLink property you can also add a hyperlink to the device display.

{
     "id": "probe6",
     "class": "HttpProbe",
     "name": "Router Web Page with Redirect",
     "url": "http://fritz.box",
     "enableResponseTime": true,
     "interval": 60,
     "maxRedirects": 0,
     "xLink": "http://fritz.box",
     "xAttributeOptions": [
         {
           "name": "responseTime",
           "displaySparkline": false
         }
     ]
 }

As part of the device definition you need to provide the host and portfor the TCP Service to be probed. If the property enableConnectTime is set to true (false by default) the device will additionally expose a connectTime attribute, which allows for monitoring the connection establishment times. You may also set the interval property to specify the probing interval in seconds (60 seconds by default). The timeout property may be set to specify the idle timeout on the TCP socket in seconds (10 seconds by default).

{
      "id": "probe7",
      "class": "TcpConnectProbe",
      "name": "Call Monitor",
      "host": "fritz.box",
      "port": 1012,
      "enableConnectTime": false,
      "interval": 10,
      "timeout": 10
}

If you wish to hide the sparkline (the mini-graph) of connectTime attribute display this is possible with pimatic v0.8.68 and higher using the xAttributeOptions property as shown in the following example. Using the xLink property you can also add a hyperlink to the device display.

{
    "id": "probe8",
    "class": "TcpConnectProbe",
    "name": "Call Monitor",
    "host": "fritz.box",
    "port": 1012,
    "enableConnectTime": true,
    "interval": 10,
    "timeout": 10
    "xLink": "http://fritz.box",
    "xAttributeOptions": [
         {
           "name": "connectTime",
           "displaySparkline": false
         }
    ]
}

See Release History.

Copyright (c) 2015-2019, Marcus Wittig and contributors. All rights reserved.

License: GPL-2.0.