pimatic-probe

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

Contributions

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.

Configuration

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.

HttpProbe Configuration

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
}

HttpProbe Advanced Configuration

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

HTTP Response Status Codes

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
}

HTTP Basic Authentication

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
    ]
}

HTTPS Server Certificate Verification

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
    ]
}

HTTP Redirect

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
}

xLink and xAttributeOptions properties

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
         }
     ]
 }

TcpConnectProbe Configuration

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
}

TcpConnectProbe Advanced Configuration

xLink and xAttributeOptions properties

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
         }
    ]
}

History

See Release History.

License

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

License: GPL-2.0.