/pingcheck

Check connectivity of interfaces in OpenWRT

Primary LanguageCGNU General Public License v2.0GPL-2.0

pingcheck

Check connectivity of network interfaces in OpenWRT

Checks wether a configured host (normally on the Internet) can be reached via a specific network interface. Then makes this information available via ubus and triggers "online" and "offline" scripts. It's like "hotplug" for internet connectivity and especially useful if your router could be connected via multiple interfaces (say Ethernet, Wifi or UMTS) at the same time. The check can be done with classic ICMP echo requests (like ping) or by opening a TCP connection to a web-server (or any TCP server), which can be useful when ICMP is blocked by a firewall.

Config options

Section default or section interface

Name Type Required Default Description
host IP address yes (none) IP Address or hostname of ping destination
interval seconds yes (none) Ping will be sent every 'interval' seconds
timeout seconds yes (none) After no Ping replies have been received for 'timeout' seconds, the offline scripts will be executed
protocol icmp or tcp no icmp Use classic ICMP ping (default) or TCP connect
tcp_port port number no 80 TCP port to connect to when protocol is tcp
panic minutes no (not used) If the system is OFFLINE for more than this time, the scripts in '/etc/pingcheck/panic.d' will be called

All these values can either be defined in defaults, or in the interface, but the are required in one of them. Interface config overrides default.

Section interface

Name Type Required Default Description
name interface name yes (none) UCI name of interface

Here is an example config:

config default
        option host 8.8.8.8
        option interval 10
        option timeout 30

config interface
        option name wan
        # default options will be used

config interface
        option name sta
        option host 192.168.11.1

config interface
        option name umts
        option interval 5
        option timeout 60

config interface
        option name bat_cl

ubus Interface

The overview status shown on ubus looks like this:

root@OpenWrt:~# ubus call pingcheck status
{
        "status": "ONLINE",
        "online_interfaces": [
                "wan",
                "sta"
        ],
        "known_interfaces": [
                "wan",
                "sta",
                "umts",
                "bat_cl"
        ]
}

Detailed interface status is also available:

root@OpenWrt:~# ubus call pingcheck status "{'interface':'sta'}"
{
        "status": "ONLINE",
        "interface": "sta",
        "device": "wlan1",
        "percent": 100,
        "sent": 16,
        "success": 16,
        "last_rtt": 101,
        "max_rtt": 136
}

You can reset the counters and interface status for all interfaces like this:

root@OpenWrt:~# ubus call pingcheck reset

Or for just one specific interface:

root@OpenWrt:~# ubus call pingcheck reset '{"interface":"wan"}'

Shell Scripts

When a interface status changes, scripts in /etc/pingcheck/online.d/ or /etc/pingcheck/offline.d/ are called and provided with INTERFACE, DEVICE and GLOBAL environment variables, similar to hotplug scripts.

Variable Description
INTERFACE logical network interface (e.g. wan) which goes online or offline
DEVICE physical device (e.g. eth0) which goes online or offline
GLOBAL ONLINE or OFFLINE depending on wether device is online thru other interfaces

Additionally, if option panic is set, scripts in /etc/pingcheck/panic.d/ are called after the system has been globally offline for more than panic minutes.