freebox-lan-monitor

Monitors devices present in Freebox (French Internet Provider box) Local Area Network (LAN). Sends notifications to a MQTT server when devices are entering or leaving network in order to pass on events to another process (such as home automation sofware).

Description

This Shell script monitors devices on a Freebox LAN using Freebox API. It leverages "push notifications" from the Freebox Server (websocket): instead of regularly polling the network, the script subscribes to router's events. Hence, this approach can be less resource greedy and is quicker to react to network changes.

However, do not expect near real-time feedback on devices' reachability.

My use case is to trigger some home automation routines based on my smartphone and smartwatch presence on the network (ie. tracking WiFi connectivity). Notifications are pushed to a MQTT Server on which my home automation software is subscribed to.

Prerequisites

Freebox Server (tested on Freebox Delta)
Always on computer able to run bash script (tested on macOS & Raspberry PI)
curl command
jq command
websocat command
optional: mosquitto_pub command

Dependencies

Dependencies commands must either be available in PATH or directly put in the same directory as freebox-lan-monitor.sh script.

Check curl is avaible in PATH. If not download it.
Check jq is avaible in PATH. If not download it from jq.
Check websocat is avaible in PATH. If not install it from websocat.
Optional: install mosquitto_pub using sudo apt-get install mosquitto

NB: I observed that jq 1.5 is way more faster than 1.6 under macOS. You shall install jq 1.5 if running under macOS.

Installation

Create a dedicated directory (eg. freebox-lan-monitor)
Download freebox-lan-monitor.sh to dedicated directory
Make script executable using chmod +x ./freebox-lan-monitor.sh
Execute script ./freebox-lan-monitor.sh
First time execution will require you to grant Freebox access to the script. Go to your Freebox front panel to approve access
Check log entry LAN devices monitoring registration successful confirming script is executing properly
Stop script (hitting ctrl-c)
Optional: if you wish to use MQTT, edit config file config/mqtt_config.json (see below)
Execute script in background ./freebox-lan-monitor.sh &

Making it a service

On RPI:

Edit config/freebox-lan-monitor.service and adapt ExecStart , WorkingDirectory and User settings accordingly
Copy config/freebox-lan-monitor.service file to /etc/systemd/system/
Execute sudo systemctl enable freebox-lan-monitor.service
Execute sudo systemctl freebox-lan-monitor.service

Configuration

If you wish to push MQTT messages, config/mqtt_config.json file shall contains the following keys/values:

Key	Default	Description
`mosquitto_pub_params`	N/A	Parameters passed to mosquitt_pub command along with pushed message. eg. "-h rpi4.local" (to pass MQTT broker hostname)
`mqtt_topic`	N/A	MQTT topic name to which messages will be added. eg. "freebox-lan-monitor"

Configuration sample:

{
   "mosquitto_pub_params": "-h rpi4.local",
   "mqtt_topic" : "freebox-lan-monitor"
}

Auto reconnect Freebox API for monitorLAN() function

Dear Matsuo3rd
Sorry for this second issue... but it's another subject so I did separate it from the other informative only issue

I've seen the TODO

#TODO: try reconnect:ws://....

in your function :

monitorLAN() {
	log "LAN devices monitoring registration in progress"
	#TODO: try reconnect:ws://....
	echo '{"action": "register", "events": ["lan_host_l3addr_reachable", "lan_host_l3addr_unreachable"]}' \
		| ${WEBSOCAT} --ping-timeout 120 --ping-interval 60 --text --no-close -H="X-Fbx-App-Auth: ${session_token}" ${FREEBOX_API_WS_BASE_URL}/ws/event \
		| while read notification; do
			#log "${notification}"
			processLANNotification "${notification}"
	done

	warn "LAN devices monitoring stopped. Relaunching."
	while [[ "$(curl -s -o /dev/null -w ''%{http_code}'' --connect-timeout 5 ${FREEBOX_APP_HOSTNAME})" != "200" ]];
	do
			warn "Freebox endpoint could not be reached. Retrying ..."
			sleep 5
	done

	login
	monitorLAN
}

Using THIS LIBRARY you can have an auto reconnect to Freebox API when task are longer than the session timeout (I use it when monitoring filesystem tasks that can make more than 1 day to complete):

source the lib (after configuring a apssword inside and optional URLs / TLS certificates
create an application with function 'authorize_application'
login API with login function
and use function 'relogin_freebox' which made the job for you

See the 'LOGIN FUNCTION' part of the library README.md LOGIN

You may also be interrested in other functions of the library (which is not using 'jq' but some 100% pure bash functions to parse JSON)

Hope it could help...

I'm also working on the way to mask data in BASH as describes in RFC 6455 for making websocket connections directly from bash without websocat (I want to use the less possible external tool for using the library on certain UNIX systems like SOLARIS or AIX on which I can have only curl and openssl (no websocat even if I build it myself, no jq, ...))

Kind regards
nbanba

matsuo3rd / freebox-lan-monitor Goto Github PK