Merge pull request #80 from highvolt-dev/enhancement/alternative_conn…

…ectivity_test

add support for alternative connectivity checks - fixes #13 #78 ; add…

README.md

@@ -4,7 +4,7 @@
 
 # tmo-monitor
 
-A lightweight, cross-platform Python 3 script that can monitor the T-Mobile Home Internet Nokia and Arcadyan 5G Gateways for 4G/5G bands, cellular site (tower), and internet connectivity and reboots as needed or on-demand.
+A lightweight, cross-platform Python 3 script that can monitor the T-Mobile Home Internet Nokia, Arcadyan, and Sagecom 5G Gateways for 4G/5G bands, cellular site (tower), and internet connectivity and reboots as needed or on-demand.
 
 By default, checks for n41 5G signal and connectivity to google.com via ping.
 
@@ -32,44 +32,51 @@ When in doubt, consult this document or run `tmo-monitor.py --help`.
 
 ### Command line usage
 ```
-usage: tmo-monitor.py [-h] [-I INTERFACE] [-H PING_HOST]
-                      [--ping-count PING_COUNT]
-                      [--ping-interval PING_INTERVAL] [-6] [-R] [-r] [--skip-bands]
-                      [--skip-5g-bands] [--skip-ping] [--skip-enbid]
+usage: tmo-monitor.py [-h] [--connectivity-check {ping,http}]
+                      [-I INTERFACE]
+                      [--http-target HTTP_TARGET] [--status-code {[100,600)}]
+                      [-H PING_HOST] [--ping-count PING_COUNT] [--ping-interval PING_INTERVAL] [-6]
+                      [-R] [-r]
+                      [--skip-bands] [--skip-5g-bands] [--skip-connectivity-check] [--skip-enbid]
                       [--uptime UPTIME]
-                      [-4 {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}]
-                      [-5 {n41,n71}] [--enbid ENBID] [--print-config] [--logfile LOGFILE]
-                      [--log-all] [--log-delta]
-                      [--model {NOK5G21,ARCKVD21}]
+                      [-4 {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}] [-5 {n41,n71}]
+                      [--enbid ENBID]
+                      [--print-config]
+                      [--logfile LOGFILE] [--log-all] [--log-delta] [--syslog]
+                      [--model {NOK5G21,ARCKVD21,FAST5688W}]
                       [username] [password]
 
-Check T-Mobile Home Internet cellular band(s) and connectivity and reboot if
-necessary
+Check T-Mobile Home Internet cellular band(s) and connectivity and reboot if necessary
 
 positional arguments:
   username              the username (most likely "admin")
-  password              the administrative password (will be requested at
-                        runtime if not passed as argument)
+  password              the administrative password (will be requested at runtime if not passed as argument)
 
 optional arguments:
   -h, --help            show this help message and exit
+  --connectivity-check {ping,http}
+                        type of connectivity check to perform (defaults to ping)
   -I INTERFACE, --interface INTERFACE
                         the network interface to use for ping. pass the source IP on Windows
+  --http-target HTTP_TARGET
+                        the URL to perform a http check against (defaults to https://google.com/generate_204)
+  --status-code {[100,600)}
+                        expected HTTP status code for http connectivity check (defaults to 204)
   -H PING_HOST, --ping-host PING_HOST
                         the host to ping (defaults to google.com)
   --ping-count PING_COUNT
-                        how many ping health checks to perform
+                        how many ping health checks to perform (defaults to 1)
   --ping-interval PING_INTERVAL
-                        how long in seconds to wait between ping health checks
+                        how long in seconds to wait between ping health checks (defaults to 10)
   -6, --ping-6          use IPv6 ping
   -R, --reboot          skip health checks and immediately reboot gateway
   -r, --skip-reboot     skip rebooting gateway
   --skip-bands          skip check for connected 4g band
   --skip-5g-bands       skip check for connected 5g band
-  --skip-ping           skip check for successful ping
+  --skip-connectivity-check, --skip-ping
+                        skip connectivity check
   --skip-enbid          skip check for connected eNB ID
-  --uptime UPTIME       how long the gateway must be up before considering a
-                        reboot (defaults to 90 seconds)
+  --uptime UPTIME       how long the gateway must be up before considering a reboot (defaults to 90 seconds)
   -4 {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}, --4g-band {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}
                         the 4g band(s) to check
   -5 {n41,n71}, --5g-band {n41,n71}
@@ -79,7 +86,8 @@ optional arguments:
   --logfile LOGFILE     output file for logging
   --log-all             always write connection details to logfile
   --log-delta           write connection details to logfile on change
-  --model {NOK5G21,ARCKVD21}
+  --syslog              log to syslog
+  --model {NOK5G21,ARCKVD21,FAST5688W}
                         the gateway model (defaults to NOK5G21)
 ```
 
@@ -90,11 +98,25 @@ optional arguments:
 
 By default, the script will assume the silver-colored Nokia NOK5G21 gateway is being used.
 
-Valid values are `NOK5G21` for the Nokia gateway, or `ARCKVD21` for the square, black-colored Arcadyan gateway.
+Valid values are `NOK5G21` for the Nokia gateway, `ARCKVD21` for the square, black-colored Arcadyan gateway without top vent holes, or `FAST5688W` for the square, black-colored Sagecom gateway with top vent holes.
+
+### Connectivity check
+**Mode:** `--connectivity-check`
+    Defaults to `ping`. Can instead use a HTTP(S) based health check with the `http` value. The `http` health check defaults to checking `https://google.com/generate_204` and checking its status code. _All connectivity checks will respect the `-I --interface` flag_.
 
-### Ping options
 **Interface:** `-I --interface`
-    Can be used to specify the network interface used by the ping command. Useful if T-Mobile Home Internet is not your default network interface: e.g., this is running on a dual WAN router. On Windows, pass the source IP address to use.
+    Can be used to specify the network interface used by the ping command. Useful if T-Mobile Home Internet is not your default network interface: e.g., this is running on a dual WAN router. On Windows, pass the source IP address to use. `http` connectivity checks will be dictated by system routing rules.
+
+### HTTP check
+**Target:** `--http-target`
+    Defaults to `https://google.com/generate_204` - both `http` and `https` targets are supported by the `http` value of the `--connectivity-check` flag.
+
+**Status Code:** `--status-code`
+    Defaults to `204` for use with `https://google.com/generate_204` - in most common use cases, a `200` status code is expected instead. Expects a numeric value between 100-599 (inclusive).
+
+### Ping options
+
+`ping` checks are the default connectivity check in `tmo-monitor`. It's possible to use HTTP(S)-based checks instead. Refer to the `--connectivity-check` flag.
 
 **Ping Host:** `-H --ping-host`
     Defaults to `google.com` - override if you'd like to ping an alternate host to determine internet connectivity. Must specify a host if flag is provided - you can simply omit the flag if you'd like to use the default google.com ping check.
@@ -121,8 +143,8 @@ Valid values are `NOK5G21` for the Nokia gateway, or `ARCKVD21` for the square,
 **Skip 5g Bands:** `--skip-5g-bands`
     Skip check for connected 5g band.
 
-**Skip Ping:** `--skip-ping`
-    Skip check for successful ping.
+**Skip Ping:** `--skip-connectivity-check --skip-ping`
+    Skip check for successful connectivity check.
 
 **Uptime Threshold:** `--uptime`
     Defaults to 90 seconds - Specify a required uptime for an implicit reboot to occur. Intended to allow sufficient time to establish a connection and stabilize band selection. Setting is used to avoid boot looping, but is not respected when the `--reboot` flag is used.

bin/tmo-monitor.py

@@ -61,7 +61,8 @@
 
   if config.model == GatewayModel.NOKIA:
     gw_control = TrashCanController(config.login['username'], config.login['password'])
-  elif config.model == GatewayModel.ARCADYAN:
+  # The Arcadyan and Sagecom gateways appear to conform to the same API
+  elif config.model in [GatewayModel.ARCADYAN, GatewayModel.SAGECOM]:
     gw_control = CubeController(config.login['username'], config.login['password'])
   else:
     raise Exception('Unsupported Gateway Model')
@@ -105,14 +106,22 @@
         print('Camping on ' + band_5g + '.')
 
     # Check for successful ping
-    ping_ms = gw_control.ping(config.ping['ping_host'], config.ping['ping_count'], config.ping['ping_interval'], config.ping['interface'], config.ping['ping_6'])
+    ping_ms = gw_control.ping(config.ping['ping_host'], config.ping['ping_count'], config.ping['ping_interval'], config.connectivity['interface'], config.ping['ping_6'])
     if log_all:
       connection['ping'] = ping_ms
-    if ping_ms < 0:
+    if ping_ms < 0 and config.connectivity['connectivity_check'] == 'ping':
       logging.error('Could not ping ' + config.ping['ping_host'] + '.')
       if config.reboot['ping']:
         reboot_requested = True
 
+    # Check for successful http check
+    if config.connectivity['connectivity_check'] == 'http':
+      status_code = gw_control.http_check(config.http['http_target'])
+      if status_code != config.http['status_code']:
+        logging.error('Status code failed check for ' + config.http['http_target'] + ' - received status code ' + str(status_code))
+        if config.reboot['http']:
+          reboot_requested = True
+
   # Reboot if needed
   reboot_performed = False
   if (reboot_requested or log_all):

example.env

@@ -16,36 +16,44 @@ tmo_ping_reboot=True
 tmo_print_config=True
 
 # Gateway model
-# tmo_model             # {'NOK5G21' | 'ARCKVD21' } The gateway model (defaults to NOK5G21)
+# tmo_model              # {'NOK5G21' | 'ARCKVD21' | 'FAST5688W' } The gateway model (defaults to NOK5G21)
 
 # Trashcan login settings
-# tmo_username          # defaults to 'admin'
-# tmo_password          # if not supplied, will be prompted interactively
+# tmo_username           # defaults to 'admin'
+# tmo_password           # if not supplied, will be prompted interactively
+
+# Connectivity check
+# tmo_connectivity_check # {'ping' | 'http' } Type of connectivity check to perform (defaults to ping)
+# tmo_interface          # The network interface to use for ping. Pass the source IP on Windows. http checks use system routing rules.
+
+# HTTP checks
+# tmo_http_target        # HTTP connectivity test target (defaults to https://google.com/generate_204)
+# tmo_status_code        # The expected HTTP status code for HTTP connectivity tests (defaults to 204)
 
 # Ping configuration
-# tmo_interface         # The network interface to use for ping. Pass the source IP on Windows.
-# tmo_ping_host         # The host to ping (defaults to 'google.com')
-# tmo_ping_count        # How many pings to perform before rebooting (defaults to 1)
-# tmo_ping_interval     # The interval between pings (defaults to 10)
-# tmo_ping_6            # {True | False } Use IPv6 ping
+# tmo_ping_host          # The host to ping (defaults to 'google.com')
+# tmo_ping_count         # How many pings to perform before rebooting (defaults to 1)
+# tmo_ping_interval      # The interval between pings (defaults to 10)
+# tmo_ping_6             # {True | False } Use IPv6 ping
 
 # Connection configuration
-# tmo_primary_band      # 4G band: comma-separated list from {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}
-# tmo_secondary_band    # 5G band: comma-separated list from {n41,n71}
-# tmo_enbid             # eNB ID
+# tmo_primary_band       # 4G band: comma-separated list from {B2,B4,B5,B12,B13,B25,B26,B41,B46,B48,B66,B71}
+# tmo_secondary_band     # 5G band: comma-separated list from {n41,n71}
+# tmo_enbid              # eNB ID
 
 # Reboot settings: minimum uptime (seconds) & reboot on failed check {True, False}
 # Note that these semantics differ from command line arguments!
-# tmo_skip_reboot       # overrides all other reboot options
-# tmo_min_uptime        # Minimum uptime to reboot, defaults to 90 seconds
-# tmo_ping_reboot       # {True | False } Reboot on failed ping
-# tmo_4G_band_reboot    # {True | False } Reboot on failed 4G band check
-# tmo_5G_band_reboot    # {True | False } Reboot on failed 5G band check
-# tmo_enbid_reboot      # {True | False } Reboot on failed eNB ID check
+# tmo_skip_reboot        # overrides all other reboot options
+# tmo_min_uptime         # Minimum uptime to reboot, defaults to 90 seconds
+# tmo_ping_reboot        # {True | False } Reboot on failed ping
+# tmo_http_reboot        # {True | False } Reboot on failed http connectivity test.
+# tmo_4G_band_reboot     # {True | False } Reboot on failed 4G band check
+# tmo_5G_band_reboot     # {True | False } Reboot on failed 5G band check
+# tmo_enbid_reboot       # {True | False } Reboot on failed eNB ID check
 
 # General settings
-# tmo_print_config      # {True | False } Output configuration to console
-# tmo_logfile           # Filename for logging output (default: 'tmo-monitor.log')
-# tmo_log_all           # {True | False }  Log all connection statistics
-# tmo_log_delta         # {True | False }  Log any change in connection statistics
-# syslog                # {True | False }  Log to syslog
+# tmo_print_config       # {True | False } Output configuration to console
+# tmo_logfile            # Filename for logging output (default: 'tmo-monitor.log')
+# tmo_log_all            # {True | False }  Log all connection statistics
+# tmo_log_delta          # {True | False }  Log any change in connection statistics
+# syslog                 # {True | False }  Log to syslog