Struggles scripting with the restful API...

[ASteve]

I want to write a script that polls my opnsense server [ Version 22.7.11 ] and triggers an action if either of the upstream gateways is down.  Essentially, I want a 'health-check' of my (two) internet connections from a script on my local LAN.

My first idea was to use the published Rest API.  I configured an user, generated an API Key and started to experiment with the APIs I found in the documentation.

I was able to use Curl to GET from https://$OPNSENSEHOST/api/core/firmware/status - which yielded sensible-looking JSON.  Things didn't go so well when I tried to find an API call to give me the status of my two gateway interfaces.  For example, I tried using https://$OPNSENSEHOST/api/interfaces/overview/export - but it returned code 400 with the message: "controller OPNsense\\Interfaces\\Api\\OverviewController not found".  I'm not sure why - as this API call does seem to have (sparse) documentation.

• Am I misinterpreting the API documentation?
• Does OpnSense support scripted (Restful) queries about the status of gateway interfaces? (I'm running dpinger Gateway Monitor services - and the information I want in my script is presented in the dashboard under "Gateways")
• Is the Rest API the best way to query gateway status from a script run on a host on my LAN?

[allddd]

and triggers an action if either of the upstream gateways is down.

Not sure about the API, but have you considered using Monit? It's designed to do exactly that.
It can notify you, execute a script, or basically do anything else you want it to.

https://docs.opnsense.org/manual/monit.html

[ASteve]

and triggers an action if either of the upstream gateways is down.

Not sure about the API, but have you considered using Monit? It's designed to do exactly that.
It can notify you, execute a script, or basically do anything else you want it to.

https://docs.opnsense.org/manual/monit.html

Thanks for recommending Monit... it's related to what I'm trying to do.  I have Monit set up... but I'm trying to achieve something subtly different.  Monit can't do what I want because I want the decision about presence/absence of a fault-condition to be made by a host on my LAN - not by the host running OpnSense.

With Monit, while it could run a script (on the OpnSense router) when relevant fault conditions arise... I want a script to periodically verify that the gateway is operating properly.  I don't want my OpnSense router to push notifications of faults... I want a script that runs on a separate host (on my LAN) to poll to check the opposite - i.e. that both uplinks are 'OK'.  I make a distinction between the approaches as they have different failure modes. If some aspect of my networks (LAN/WAN/VPN etc.) is down, this could plausibly block delivery of a message about failure (giving the false impression that everything is OK).  Conversely, if I take a polling approach - dispatching requests (perhaps once a minute) from a host I'm actively using... then any failure to verify things are "OK" (whatever the reason for that failure) will permit reliable notification about there being some kind of problem.  Another obvious distinction between the approaches:  if power to my OpnSense router fails (unplugged/switched off at mains) then the Monit service on it will not be dispatching any notifications.  Conversely, if a service running on my desktop (which I'm actively using) fails to successfully poll the router, and verify things are OK, then it will be able to actively notify me - even if the LAN and/or WAN are not working properly; even if email and/or DNS are not working properly.

[allddd]

Does it have to be an LAN host, or would it be OK for an external service to notify you?

You could use a service like https://healthchecks.io in combination with Monit. This would be even more reliable, since you would receive a notification regardless of whether you are currently using the system or not.

You can configure Monit to send an HTTP request to healthchecks.io every time a check is successful. If it fails for any reason, or if OPNsense cannot reach healthchecks.io at all, you will be notified. They offer a generous free tier, you can even receive calls and SMS.

[ASteve]

Does it have to be an LAN host, or would it be OK for an external service to notify you?

You could use a service like https://healthchecks.io in combination with Monit. This would be even more reliable, since you would receive a notification regardless of whether you are currently using the system or not.

While a service like healthchecks.io would be fantastic in lots of scenarios, it isn't a good solution for the problem I'm trying to solve.

The risk I'm trying to eliminate is one in which things stop working while I'm at my desk... in a location where I could address any transitory problem - if I had noticed the issue.  I have poor mobile phone signal and rely upon Wi-Fi calling (which relies upon my router) and all email is also dependent upon the same local networks and services.  I plan to write a script that will make many checks - covering all sorts of services I run on my LAN... and to have it drive a small GUI app on my desktop computer report a green ":-)" or red ":-(" icon on my task bar (alongside any error message generated from my script).

I've already evaluated services that (try to) push notifications to me over the Internet. I see such facilities as being very useful in some circumstances... but I particularly want to be able to monitor from my LAN to verify that everything on my router is 'happy' - and that my local services have not failed/stopped.  I can only administer my OpnSense router and local services from my LAN - so I gain little if I get notifications on my mobile phone when I'm not at my desk. I'm aware of two potential strategies to query the status of my internet up-links from a host on my LAN:

• Use the restful API for OpnSense.  I'm not sure which API calls I should use as the documentation doesn't seem very helpful/informative/accurate/complete.
• Run some command-line tool(s) on the OpnSense host over SSH. I'm aware of configctl, for example, but I'm not sure which OpenSSH command-line tool would give the most appropriate diagnostic output.

I had hoped that the Rest API would be perfect for my purposes (though I'm struggling to establish how to use it in practise).  I'm aware of tools like configctl, which I can run over SSH, but it's not clear to me how I can get them to yield the status information that's of interest to me.  For the problem I'm trying to tackle, I definitely want to automate my own scripted checks.. that I will write, which will be run on a host connected to my LAN, rather than purchase some additional external service.  I'm surprised at how difficult this has proven to be with OpnSense.