VPNMON VPNMON-R3 v1.3.3 -Apr 2, 2024- Monitor WAN/Dual-WAN/VPN Health & Reset Multiple OpenVPN Connections (Now available in AMTM!)

[Viktor Jaep]

VPNMON-R3 v1.3.3
Updated April 2, 2024

Executive Summary: VPNMON-R3 (vpnmon-r3.sh) is an all-in-one script that is optimized to maintain multiple OpenVPN connections and is able to provide for the capabilities to randomly reconnect using a specified server list containing the servers of your choice. Special care has been taken to ensure that only the VPN connections you want to have monitored are tended to. This script will check the health of up to 5 VPN connections on a regular interval to see if monitored VPN connections are connected, and sends a ping to a host of your choice through each active connection. If it finds that a connection has been lost, it will execute a series of commands that will kill that single VPN client, and randomly picks one of your specified servers to reconnect to for each VPN client. It also monitors your WAN/Dual-WAN connection and drops back until your WAN connection comes back up to reconnect your VPN tunnels.

VPNMON is free to use under the GNU General Public License version 3 (GPL 3.0).

This project is hosted on GitHub

Changelog here / Jump to Latest Release / What's new: AMTM Email Notifications, Skynet Whitelisting, Reset > Ping Value, WAN/Dual-WAN Monitoring, Pause on -RESET, Added Connected Time, Added PING stats, Added Unbound-over-VPN, Added Server List Automation, Initial Beta Release!

Examples & Tutorials -- further help on how to create custom CURL+JQ statements for your VPN Client Slot Server Lists available here

Screenshot:

Assumptions​

• Functional VPN Environment -- You must already have a working VPN client environment. This means, your VPN client(s) must already be in working order using your current VPN provider. When you slide that VPN client switch to the "ON" position in your Merlin Firmware UI, your VPN client must be able to make a successful connection. Make sure each client works (up to 5) if you want these to be monitored by VPNMON-R3.
• VPN Director has been configured -- You must have allocated which devices you want to talk to which VPN connections using the VPN Director function within the Merlin Firmware.
• VPN Server IP List Creation -- In order to generate VPN server lists for your individual clients, you must be able to gather the IP addresses of the VPN servers from your VPN provider that you want each VPN client to make a connection with. These IP addresses need to be entered in (or copied into) each of the (up to) 5 server lists using the VPNMON-R3 "Update/Maintain VPN Server Lists" functionality as a single column of IPv4 addresses.
• Standard Configuration Basics -- As with practically running any custom script on your router, you must at least have an external USB drive installed, formatted with a swap file and with Entware enabled using AMTM. Last, you must also have enabled JFFS scripting through your Merlin Firmware UI.

Use-case​

• You may be running multiple VPN connections dedicated to specific devices on your network (TV/Streaming, family devices, IoT devices, testing, etc.).
• You may be using multiple VPN providers, say NordVPN on one connection, and SurfShark on another.
• You may want control over which selection of VPN servers these VPN clients can reconnect to.
• You want a monitoring tool to ensure each of your monitored VPN connections remain healthy, and will initiate a reconnection if any ping or curl test fails across the tunnel, giving you peace of mind that your VPN environment will achieve maximum uptime.

How is this script supposed to run?​

It is highly recommended to run this script from a SCREEN utility window running directly on the router itself, reachable through its own SSH window... but could very well just run from a PC that's connected directly to the Asus router, as it loops and checks the connection every 60 seconds. Instructions:

1. Download and install directly using your favorite SSH tools, copy & paste this command (or install directly from AMTM!):
   

   curl --retry 3 "https://raw.githubusercontent.com/ViktorJp/VPNMON-R3/main/vpnmon-r3.sh" -o "/jffs/scripts/vpnmon-r3.sh" && chmod 755 "/jffs/scripts/vpnmon-r3.sh"

2. To initially configure this script, open up a dedicated SSH window, and simply execute the script:
   

   sh /jffs/scripts/vpnmon-r3.sh -setup

3. Once you've successfully configured the various options, you can run the script using this command:
   

   sh /jffs/scripts/vpnmon-r3.sh

4. To make life easier, can now also just launch or reconnect to VPNMON-R3 with the -screen switch to allow it run in the background without needing a dedicated SSH window connection. Type:
   

   vpnmon-r3 -screen

 

[Viktor Jaep]

Instructions & Directions

Operations Menu
From the main UI, you can press (S)how Operations Menu, as shown below. This gives you quick access to: Resetting/Stopping individual VPN Client Slots, enable/disable monitored VPN slots, maintain your VPN server lists assigned to each VPN Client Slots, run server list automations, open the Setup/Config menu, view event logs, enable/disable auto start settings on router reboot, set a scheduler to reset your VPN connections, adjusting your timer loop preference and configuring the max # of milliseconds a VPN ping can get to before it forces a reset.

Setup/Configuration Menu
The Main Setup and Configuration Menu allows you to enter the Custom Configuration Options Menu, force re-install Entware Dependencies, checking and installing updates to the script, and an uninstall option.

Configuration Options
The number of options are short & sweet (compared to VPNMON-R2). Here you can specify how many VPN Client Slots you have available (some routers only have 3 due to NVRAM size limitations), which custom host you want to use to PING against, how large you want your event log to grow to, whether or not you want to enable the Unbound-over-VPN integration, and whether or not you want your custom server list queries to refresh when your connection gets reset using the -reset switch. Recently added was the ability to also monitor your WAN connection for failures, adding your VPN Server IP lists to the Skynet whitelist, and enabling email notifications based on success or failure.

VPN Client Monitoring
Pressing the (M) key from the main UI, you will have the option to choose which individual VPN Client Slots you want VPNMON-R3 to monitor. Once enabled, each item will show a green "Y", and VPNMON-R3 will probe these connections to test and ensure they can PING and CURL to determine their health. Should one of these commands fail, VPNMON-R3 will reset its connection.

 

[Viktor Jaep]

VPN Server List Maintenance
Each VPN Client Slot has an associated VPN Server List. Each list is used as a preferred list of VPN servers that each VPN Client Slot can make connections to. To edit a certain list, press the (#) for the associated VPN Server List. IMPORTANT NOTE: If you don't specify a server list, VPNMON-R3 will just try to reconnect to the currently configured VPN Server hostname/IP of your VPN Client Slot.

When you press a (#) to edit a VPN Server List, the NANO text editor will present you with the contents of the list. Here, you can enter your preferred list of IPv4 VPN Server IP addresses (or valid hostnames) in a single column as shown below. Please don't include any other text or info. Once you're done editing, press CTRL-O + ENTER to save the file. Then press CRTL-X to exit.

VPN Client Slot Server List Automation

This functionality allows you to enter a CURL statement that queries your particular VPN Provider for a specific list of VPN Server IP addresses... for the country or city of your choice. It then automatedly dumps those results into your VPN Client Slot Server List files, and is a good way to refresh these to your liking. These lists will automatically refresh on reset when you have enabled this option under the config menu. Recently added, is now also the ability to import your list contents into Skynet for whitelisting purposes.

I have created a thread of sample CURL statements that you can run with and modify if you are interested in automating this function a bit more... It shows examples from the various VPN Providers that are supported in VPNMON-R2 , like dumping all of NordVPN's Atlanta servers into a single column, for example:

curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "Atlanta") | .station'

But you can basically get as CrAzY or as creative as you want, as long as it generates a single column of IP addresses/hostnames. I have a created a post with more guidance and examples here:

VPNMON - VPNMON-R3 Custom Server List Generation Tutorials and Examples

FULL DISCLOSURE: I absolutely SUCK at JQuery... 😋 It's not like SQL at all, which I'm pretty decent with. I think the reason I am no good at this is because the sources this data comes from is always structured very differently in JSON, so there's always a completely different way at getting at...

www.snbforums.com

 

[Ripshod]

Subbed

 

[Ripshod]

What can I say? Nothing yet - testing

 

[Viktor Jaep]

What can I say? Nothing yet - testing

Lookin' good! Hoping to have some instructions completed by today... if you come across anything that might require more explanation, let me know, and I can get that added as well.

 

[Ripshod]

Lookin' good! Hoping to have some instructions completed by today... if you come across anything that might require more explanation, let me know, and I can get that added as well.

I haven't seen you mention removing R2, or I just missed it?

 

[Viktor Jaep]

I haven't seen you mention removing R2, or I just missed it?

It's still very much alive as it serves a completely different function compared to R3!

The primary difference is that R2 is made for single VPN connections (with heavy customization for certain VPN providers, vpnmgr and Unbound), while R3 is made for multiple VPN connections (with zero customizations for VPN providers or vpnmgr/Unbound)

 

[CaptainSTX]

It's still very much alive as it serves a completely different function compared to R3!

The primary difference is that R2 is made for single VPN connections (with heavy customization for certain VPN providers, vpnmgr and Unbound), while R3 is made for multiple VPN connections (with zero customizations for VPN providers or vpnmgr/Unbound)

I got R3 working and so far so good.

I did remove R2 since I have it set up for only a single VPN client and with a restart every night just to be sure the VPN client isn't down. I don't block devices if the VPN client fails as connectivity for my IoT devices is more important than whatever minor security increase running them through a VPN provides.

 

[Viktor Jaep]

I got R3 working and so far so good.

I did remove R2 since I have it set up for only a single VPN client and with a restart every night just to be sure the VPN client isn't down. I don't block devices if the VPN client fails as connectivity for my IoT devices is more important than whatever minor security increase running them through a VPN provides.

Great! Yeah, R3 will work just fine with a single VPN as well, though it was designed to handle multiple. If you need all the bells & whistles with tie-ins with certain VPN providers to get more stats, and functionality like SuperRandom... then R2 is the way to go.

 

[Ripshod]

Great! Yeah, R3 will work just fine with a single VPN as well, though it was designed to handle multiple. If you need all the bells & whistles with tie-ins with certain VPN providers to get more stats, and functionality like SuperRandom... then R2 is the way to go.

Glad you say that, I've already reverted to R2. Bells and whistles yeah!!

 

[kuki68ster]

Almost 24 hours, and going strong, no issues to report....

 

[Viktor Jaep]

Almost 24 hours, and going strong, no issues to report....

Appreciate the feedback greatly!

 

[Viktor Jaep]

Coming soon... VPN Client Slot Server List Automation...

WTH is that right!?

Well, this is a place where you can enter a CURL statement that queries your particular VPN Provider for a specific list of VPN Server IP addresses... for the country or city of your choice. It then automatedly dumps those results into your VPN Client Slot Server List files, and is a good way to refresh these to your liking. I will consider automating this even further and probably allow you to run a CRON job to run these on a periodic basis.

I'll also create a thread of sample CURL statements that you can run with and modify if you are interested in automating this function a bit more... I will be able to pull examples from the various VPN Providers that are supported in VPNMON-R2 , like dumping all of NordVPN's Atlanta servers into a file:

curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "Atlanta") | .station'

But you can basically get as CrAzY or as creative as you want, as long as it generates a single column of IP addresses/hostnames.

Here's the results of dumping all of NordVPN's North America VPN Servers into Slots 1 & 2

 

[kuki68ster]

Coming soon... VPN Client Slot Server List Automation...

WTH is that right!?

Well, this is a place where you can enter a CURL statement that queries your particular VPN Provider for a specific list of VPN Server IP addresses... for the country or city of your choice. It then automatedly dumps those results into your VPN Client Slot Server List files, and is a good way to refresh these to your liking. I will consider automating this even further and probably allow you to run a CRON job to run these on a periodic basis.

I'll also create a thread of sample CURL statements that you can run with and modify if you are interested in automating this function a bit more... I will be able to pull examples from the various VPN Providers that are supported in VPNMON-R2 , like dumping all of NordVPN's Atlanta servers into a file:

curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "Atlanta") | .station'

But you can basically get as CrAzY or as creative as you want, as long as it generates a single column of IP addresses/hostnames.

View attachment 54530

Here's the results of dumping all of NordVPN's North America VPN Servers into Slots 1 & 2

View attachment 54531

That will be very useful for

 

[Viktor Jaep]

Beta v0.2 is out!

What's new?
v0.2b
- ADDED: Included "VPN Client Slot Server List Automation" functionality which allows you to free-form enter in various carefully crafted CURL statements which are designed to point to your VPN Provider's API functionality in order to export out a single list of VPN Server IPs/Hostnames to be imported into your VPN Client Slot Server List files assigned to each VPN slot. These lists are used by VPNMON-R3 to randomly reconnect to one of the hosts in the list. A separate thread will be created on SNBForums.com that will give specific examples on how to format the CURL statements in order to pull VPN Server IPs for specific countries, or cities. Please note that not all VPN providers make this easy, or have an API to pull information from. Examples for NordVPN, Surfshark, AirVPN, WeVPN and PerfectPrivacy will be provided. This item is available under the Quick Access Operations Menu using the (U) key.
- MINOR: A few visual fixes here and there to standardize look & feel across screens

Download Link:

curl --retry 3 "https://raw.githubusercontent.com/ViktorJp/VPNMON-R3/main/vpnmon-r3-0.2b.sh" -o "/jffs/scripts/vpnmon-r3.sh" && chmod 755 "/jffs/scripts/vpnmon-r3.sh"

Significant Screenshots:

This functionality allows you to enter a CURL statement that queries your particular VPN Provider for a specific list of VPN Server IP addresses... for the country or city of your choice. It then automatedly dumps those results into your VPN Client Slot Server List files, and is a good way to refresh these to your liking. I will consider automating this even further and probably allow you to run a CRON job to run these on a periodic basis.

 

[kuki68ster]

Hi,

Tried, inserted the curls that you gave me yesterday, but no success today…It erased the information I already had.

 

[Viktor Jaep]

Hi,

Tried, inserted the curls that you gave me yesterday, but no success today…It erased the information I already had.

When you hit "x1", what feedback do you get? Can you also post the CURL statement you're using? I'm not having any problems on my end...

Compared to the statements I sent you, make sure a redirection statement isn't being used (where it saves it to an external file in your /jffs/scripts)... it should only look like this:

curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "New York") | .station'
curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "Johannesburg") | .station'
curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "London") | .station'

 

[kuki68ster]

When you hit "x1", what feedback do you get? Can you also post the CURL statement you're using? I'm not having any problems on my end...

Compared to the statements I sent you, make sure a redirection statement isn't being used (where it saves it to an external file in your /jffs/scripts)... it should only look like this:

curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "New York") | .station'
curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "Johannesburg") | .station'
curl --silent --retry 3 --connect-timeout 3 --max-time 6 --retry-delay 1 --retry-all-errors https://api.nordvpn.com/v1/servers?limit=16354 | jq --raw-output '.[] | select(.locations[0].country.city.name == "London") | .station'

Hi,

You nailed the issue, it was saving to an external file… With the new curl statements, it worked.

 

[Viktor Jaep]

Releasing v0.3b this evening! Big addition for Unbound-over-VPN... this is a biggie that I would miss if I had to move from R2 to R3.

What's new?
v0.3b
- ADDED: Brought over the "Unbound-over-VPN" functionality that was originally introduced in VPNMON-R2. Out of all the integrations that were present in VPNMON-R2, I felt that this was one of the most important ones, and one that I wanted to be completely functional in VPNMON-R3 if I am going to be using this full-time. Unbound by default allows you to become your own DNS resolver, however, "Unbound-over-VPN" goes a step further and encrypts your unencrypted DNS resolver traffic all the way through to your public VPN IP address, after which it traverses unencrypted to the DNS Root Servers. This excellent feature prevents your ISP or other monitoring services from snooping in on your otherwise unencrypted DNS resolver traffic that normally happens when running Unbound. Since you are your own encrypted DNS resolver, no ISPs, or other DNS services (like Quad9, Cloudfare or Google, etc) will be able to snoop on your traffic. The only entity here that could possibly snoop on this traffic would be your VPN provider, or any nefarious services monitoring inbound/outbound VPN traffic at the VPN provider level. PLEASE NOTE: "Unbound-over-VPN" is only able to bind to 1 VPN Client Slot. If you are running other VPN connections, this will continue to work, however it is not guaranteed that the other VPN connections will be able to take advantage of Unbound. Definitely something that needs to be tested. Also, if other VPN connections are reset, the VPN Client Slot tied to "Unbound-over-VPN" will go out of sync, and will attempt to reset itself. This connection will always need to be the last one to reset itself, else it will continue to stay out-of-sync.
- FIXED: Apparently I overlooked making sure JQuery was being properly referenced as required during the setup process. Thanks to @kuki68ster for noticing this! The script will now catch this and guide you through the Entware component install process.
- FIXED: In certain situations, the autostart functionality would not save a setting back to the vpnmon-r3.cfg file, and show that it was enabled. If you have this issue, simply re-save your choice, and it will make the correct changes to the .cfg file now.

Download link:

curl --retry 3 "https://raw.githubusercontent.com/ViktorJp/VPNMON-R3/main/vpnmon-r3-0.3b.sh" -o "/jffs/scripts/vpnmon-r3.sh" && chmod 755 "/jffs/scripts/vpnmon-r3.sh"

Significant Screenshots:

Under the configuration menu, a 4th option has been added to enable Unbound-over-VPN, and select which VPN Client Slot it will be tied to

The option for Unbound-over-VPN, giving more background info on its functionality and what files it interacts with to enable this functionality

The main UI will give you an indicator whether the Unbound-over-VPN resolver is in sync with your Public VPN IP address, and will reset the connection if it goes out of sync.