Skip to content

# Network Status

It is common for home automation users to want to check, and perhaps respond to, changes in the availability of Internet access. Some platforms have this functionality as an add-in, and in that case, the status is often published to an entity in Reactor.

Users of Reactor on Linux bare-metal systems can use an available script in the `tools` directory called `reactor_inet_check.sh`. This script tests Internet access by probing one of several well-known and highly-available hosts (like Amazon, Facebook, Google, etc.). On three consecutive failures of this test, `reactor_system.internet_ok` will go false. It will set the attribute to true when any test succeeds.

Linux Only

The `reactor_inet_check.sh` runs only on Linux systems that support `bash`. It does not run on Windows. If there's a community user out there who is proficient in Windows PowerShell or the legacy command processor and wants to write a script for Windows, it would make a great community add-in.

Docker?

The script cannot run within the Reactor docker container. If you are using Reactor in a docker container, the script needs to be run by `cron` or an equivalent facility on the host system (e.g. some systems, like Synology NAS, have separate task managers that may be used to schedule the repeated execution of tasks such as this).

The recommended way to run the script is by adding the following line to your `root` user's crontab so that it is run at frequent intervals by the `cron` daemon. The command `sudo crontab -u root -e` will usually put you in the editor for `root`'s crontab. Once in, the following entry should be added:

    * * * * * cd /path/to/reactor && tools/reactor_inet_check.sh

You can usually run `man 5 crontab` for an explanation of how the crontab file is formatted. Once the updated crontab is saved with the entry shown above, `cron` will check your Internet access every minute.

The default list of probe sites includes Amazon, Google, Facebook, and CloudFlare DNS. They should work well in most parts of the world, but in the event that you have problems or regional restrictions that require you to use different sites, you can modify the list of probed sites. The list is configurable by creating a `reactor_inet_check.cf` file in your `config` subdirectory. A template for this file can be found in `tools` and copied to your `config` directory (remove the `-dist` suffix from the source file). Only the configuration file should be modified; do not modify the script itself. The comments in the template file describe the form and function of each setting.

There should be at least six probe sites on your site list. Half of the listed sites should be IP addresses, not hostnames1; all hostnames should be FQDNs. All sites, whether listed by IP or name, must be able to receive and respond to ICMP pings, and be sufficiently reliable to not cause false positives (that is, the site should be among those that are generally expected to always be "up", like Google).

You can check the performance of the script and look for runtime errors and messages by examining your system log files for output from the `cron` command and daemon.

## Why Not Built In?

The Internet check is not built in to Reactor because on many systems using `ping` requires elevated privileges, so in order to run `ping` from within Reactor, Reactor itself would need to run with elevated privileges, and this is actively and aggressively discouraged. On systems where this is configurable, it's too detailed, varied and complex to test, maintain, and document for each, so running it as an external facility with a tightly-defined and -controlled purpose is a better alternative.

Updated: 8-Jun-2022

1. Using a mix of IP addresses and hostnames allows the test to function properly even if your local DNS service fails. ↩