diff --git a/README.md b/README.md index 8894a176..ec595aad 100755 --- a/README.md +++ b/README.md @@ -60,12 +60,12 @@ Get visibility of what's going on on your WIFI/LAN network. Schedule scans for d |-------------|-------------| | πŸ“₯🐳 | [Docker instructions](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md) | πŸ“₯πŸ’» | [HW install (experimental πŸ§ͺ)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) | +| πŸ“₯🟧 | [Unraid App πŸ§ͺ)](https://unraid.net/community/apps) | | πŸ“š | [All Documentation](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md) (App Usage and Configuration) | > Other Alternatives > > - Check out [leiweibau's on HW installed fork](https://github.com/leiweibau/Pi.Alert/) (maintained) -> - Check instructions for [pucherot's original code](https://github.com/pucherot/Pi.Alert/) (unmaintained) > - [WatchYourLAN](https://github.com/aceberg/WatchYourLAN) - Lightweight network IP scanner with web GUI (Open source) > - [Fing](https://www.fing.com/) - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware) > - [NetBox](https://netboxlabs.com/) - Network management software (Commercial) diff --git a/front/js/common.js b/front/js/common.js index 7fbb99e6..72352422 100755 --- a/front/js/common.js +++ b/front/js/common.js @@ -1072,7 +1072,9 @@ function clearCache() { showSpinner(); sessionStorage.clear(); localStorage.clear(); + setTimeout(() => { window.location.reload(); +}, 500); } // ----------------------------------------------------------------------------- diff --git a/front/plugins/README.md b/front/plugins/README.md index f3e279df..805fe191 100755 --- a/front/plugins/README.md +++ b/front/plugins/README.md @@ -1,51 +1,74 @@ -# πŸ“š Docs for individual plugins +# πŸ”Œ Plugins >[!NOTE] > Please check this [Plugins debugging guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_PLUGINS.md) and the corresponding Plugin documentation in the below table if you are facing issues. -## πŸ”Œ Plugins & πŸ“š Docs -| Required | CurrentScan | Unique Prefix | Data source | Type | Link + Docs | -|----------|-------------|---------------|--------------------|----------------|---------------------------------------------------------------------| -| | | APPRISE | Script | πŸ’¬ publisher | πŸ“š[_publisher_apprise](/front/plugins/_publisher_apprise/) | -| | Yes | ARPSCAN | Script | πŸ”dev scanner | πŸ“š[arp_scan](/front/plugins/arp_scan/) | -| | | CSVBCKP | Script | βš™ system | πŸ“š[csv_backup](/front/plugins/csv_backup/) | -| Yes* | | DBCLNP | Script | βš™ system | πŸ“š[db_cleanup](/front/plugins/db_cleanup/) | -| | | DDNS | Script | βš™ system | πŸ“š[ddns_update](/front/plugins/ddns_update/) | -| | Yes | DHCPLSS | Script | πŸ”dev scanner | πŸ“š[dhcp_leases](/front/plugins/dhcp_leases/) | -| | | DHCPSRVS | Script | β™» other | πŸ“š[dhcp_servers](/front/plugins/dhcp_servers/) | -| | Yes | INTRNT | Script | πŸ”dev scanner | πŸ“š[internet_ip](/front/plugins/internet_ip/) | -| | | INTRSPD | Script | β™» other | πŸ“š[internet_speedtest](/front/plugins/internet_speedtest/) | -| | | MAINT | Script | βš™ system | πŸ“š[maintenance](/front/plugins/maintenance/) | -| | | MQTT | Script | πŸ’¬ publisher | πŸ“š[_publisher_mqtt](/front/plugins/_publisher_mqtt/) | -| Yes | | NEWDEV | Template | βš™ system | πŸ“š[newdev_template](/front/plugins/newdev_template/) | -| | | NMAP | Script | β™» other | πŸ“š[nmap_scan](/front/plugins/nmap_scan/) | -| | Yes | NMAPDEV | Script | πŸ”dev scanner | πŸ“š[nmap_dev_scan](/front/plugins/nmap_dev_scan/) | -| | | NSLOOKUP | Script | β™» other | πŸ“š[nslookup_scan](/front/plugins/nslookup_scan/) | -| Yes | | NTFPRCS | Template | βš™ system | πŸ“š[notification_processing](/front/plugins/notification_processing/)| -| | | NTFY | Script | πŸ’¬ publisher | πŸ“š[_publisher_ntfy](/front/plugins/_publisher_ntfy/) | -| | | PHOLUS | Script | β™» other | πŸ“š[pholus_scan](/front/plugins/pholus_scan/) | -| | Yes | PIHOLE | External SQLite DB | πŸ”dev scanner | πŸ“š[pihole_scan](/front/plugins/pihole_scan/) | -| | | PUSHSAFER | Script | πŸ’¬ publisher | πŸ“š[_publisher_pushsafer](/front/plugins/_publisher_pushsafer/) | -| | | PUSHOVER | Script | πŸ’¬ publisher | πŸ“š[_pushover_pushsafer](/front/plugins/_publisher_pushover/) | -| Yes | | SETPWD | Template | βš™ system | πŸ“š[set_password](/front/plugins/set_password/) | -| | | SMTP | Script | πŸ’¬ publisher | πŸ“š[_publisher_email](/front/plugins/_publisher_email/) | -| | Yes | SNMPDSC | Script | πŸ”dev scanner | πŸ“š[snmp_discovery](/front/plugins/snmp_discovery/) | -| | Yes** | UNDIS | Script | β™» other | πŸ“š[undiscoverables](/front/plugins/undiscoverables/) | -| | Yes | UNFIMP | Script | πŸ”dev scanner | πŸ“š[unifi_import](/front/plugins/unifi_import/) | -| | | VNDRPDT | Script | βš™ system | πŸ“š[vendor_update](/front/plugins/vendor_update/) | -| | | WEBHOOK | Script | πŸ’¬ publisher | πŸ“š[_publisher_webhook](/front/plugins/_publisher_webhook/) | -| | | WEBMON | Script | β™» other | πŸ“š[website_monitor](/front/plugins/website_monitor/) | -| N/A | | N/A | SQL query | | N/A, but the External SQLite DB plugins work similarly | +## Plugin types + +If you want to discover or import devices into the application enable some of the `πŸ” dev scanner` plugins. The next step is to pick a notification plugin, or `πŸ’¬ publisher` plugin, to get notified about network changes. If you don't see a publisher you'd like to use, look at the [πŸ“š_publisher_apprise](/front/plugins/_publisher_apprise/) plugin which is a proxy for over 80 notification services. + +### Enabling plugins + +Plugins can be enabled via Settings, and can be disabled as needed. + +1. Research which plugin you'd like to use below and then load the required plugins in Settings via the `LOADED_PLUGINS` setting. +1. Save the changes and review the Settings of the newly loaded plugins. +1. Change the `_RUN` Setting to the recommended or custom value as per the documentation of the given setting + - If using `schedule` on a `πŸ” dev scanner` plugin, make sure the schedules are the same across all `πŸ” dev scanner` plugins + +### Disabling, Unloading and Ignoring plugins + +1. Change the `_RUN` Setting to `disabled` if you want to disable the plugin, but keep the settings +1. If you want to speed up the application, you can unload the plugin by unselecting it in the `LOADED_PLUGINS` setting. + - Careful, once you save the Settings Unloaded plugin settings will be lost (old `app.conf` files are kept in the `/config` folder) +1. You can completely ignore plugins by placing a `ignore_plugin` file into the plugin directory. Ignored plugins won't show up in the `LOADED_PLUGINS` setting. + + +## Available Plugins + +Device-detecting plugins insert values into the `CurrentScan` database table. The plugins that are not required are safe to ignore, however, it makes sense to have a least some device-detecting plugins enabled, such as `ARPSCAN` or `NMAPDEV`. + +| ID | Type | Description | Required | Data source | Detailed docs | +|---------------|----------------|------------------------------|----------|--------------------|---------------------------------------------------------------------| +| `APPRISE` | πŸ’¬ publisher | Apprise publisher plugin | | Script | [πŸ“š_publisher_apprise](/front/plugins/_publisher_apprise/) | +| `ARPSCAN` | πŸ” dev scanner | ARP scan plugin | | Script | [πŸ“šarp_scan](/front/plugins/arp_scan/) | +| `CSVBCKP` | βš™ system | CSV backup plugin | | Script | [πŸ“šcsv_backup](/front/plugins/csv_backup/) | +| `DBCLNP` | βš™ system | Database cleanup plugin | Yes* | Script | [πŸ“šdb_cleanup](/front/plugins/db_cleanup/) | +| `DDNS` | βš™ system | DDNS update plugin | | Script | [πŸ“šddns_update](/front/plugins/ddns_update/) | +| `DHCPLSS` | πŸ” dev scanner | DHCP leases plugin | | Script | [πŸ“šdhcp_leases](/front/plugins/dhcp_leases/) | +| `DHCPSRVS` | β™» other | DHCP servers plugin | | Script | [πŸ“šdhcp_servers](/front/plugins/dhcp_servers/) | +| `INTRNT` | πŸ” dev scanner | Internet IP scanner | | Script | [πŸ“šinternet_ip](/front/plugins/internet_ip/) | +| `INTRSPD` | β™» other | Internet speed test plugin | | Script | [πŸ“šinternet_speedtest](/front/plugins/internet_speedtest/) | +| `MAINT` | βš™ system | Maintenance plugin | | Script | [πŸ“šmaintenance](/front/plugins/maintenance/) | +| `MQTT` | πŸ’¬ publisher | MQTT publisher plugin | | Script | [πŸ“š_publisher_mqtt](/front/plugins/_publisher_mqtt/) | +| `NEWDEV` | βš™ system | New device template | Yes | Template | [πŸ“šnewdev_template](/front/plugins/newdev_template/) | +| `NMAP` | β™» other | Nmap scan plugin | | Script | [πŸ“šnmap_scan](/front/plugins/nmap_scan/) | +| `NMAPDEV` | πŸ” dev scanner | Nmap device scan plugin | | Script | [πŸ“šnmap_dev_scan](/front/plugins/nmap_dev_scan/) | +| `NSLOOKUP` | β™» other | NSLookup scan plugin | | Script | [πŸ“šnslookup_scan](/front/plugins/nslookup_scan/) | +| `NTFPRCS` | βš™ system | Notification processing | Yes | Template | [πŸ“šnotification_processing](/front/plugins/notification_processing/)| +| `NTFY` | πŸ’¬ publisher | NTFY publisher plugin | | Script | [πŸ“š_publisher_ntfy](/front/plugins/_publisher_ntfy/) | +| `PHOLUS` | β™» other | Pholus scan plugin | | Script | [πŸ“špholus_scan](/front/plugins/pholus_scan/) | +| `PIHOLE` | πŸ” dev scanner | Pi-hole scan plugin | | SQLite DB | [πŸ“špihole_scan](/front/plugins/pihole_scan/) | +| `PUSHSAFER` | πŸ’¬ publisher | Pushsafer publisher plugin | | Script | [πŸ“š_publisher_pushsafer](/front/plugins/_publisher_pushsafer/) | +| `PUSHOVER` | πŸ’¬ publisher | Pushover publisher plugin | | Script | [πŸ“š_publisher_pushover](/front/plugins/_publisher_pushover/) | +| `SETPWD` | βš™ system | Set password template | Yes | Template | [πŸ“šset_password](/front/plugins/set_password/) | +| `SMTP` | πŸ’¬ publisher | Email publisher plugin | | Script | [πŸ“š_publisher_email](/front/plugins/_publisher_email/) | +| `SNMPDSC` | πŸ” dev scanner | SNMP discovery plugin | | Script | [πŸ“šsnmp_discovery](/front/plugins/snmp_discovery/) | +| `UNDIS` | β™» other | Undiscoverables scan plugin | | Script | [πŸ“šundiscoverables](/front/plugins/undiscoverables/) | +| `UNFIMP` | πŸ” dev scanner | UniFi import plugin | | Script | [πŸ“šunifi_import](/front/plugins/unifi_import/) | +| `VNDRPDT` | βš™ system | Vendor update plugin | | Script | [πŸ“švendor_update](/front/plugins/vendor_update/) | +| `WEBHOOK` | πŸ’¬ publisher | Webhook publisher plugin | | Script | [πŸ“š_publisher_webhook](/front/plugins/_publisher_webhook/) | +| `WEBMON` | β™» other | Website monitor plugin | | Script | [πŸ“šwebsite_monitor](/front/plugins/website_monitor/) | + > \* The database cleanup plugin (`DBCLNP`) is not _required_ but the app will become unusable after a while if not executed. > > \** The Undiscoverables plugin (`UNDIS`) inserts only user-specified dummy devices. -> [!NOTE] -> You soft-disable plugins via Settings or completely ignore plugins by placing a `ignore_plugin` file into the plugin directory. The difference is that ignored plugins don't show up anywhere in the UI (Settings, Device details, Plugins pages). The app skips ignored plugins completely. Device-detecting plugins insert values into the `CurrentScan` database table. The plugins that are not required are safe to ignore, however it makes sense to have a least some device-detecting plugins (that insert entries into the `CurrentScan` table) enabled, such as `ARPSCAN` or `PIHOLE`. You can also load/unload Plugins with the `LOADED_PLUGINS` setting. - > It's recommended to use the same schedule interval for all plugins responsible for discovering new devices. +## Developing custom plugins + If you want to develop a custom plugin, please read this [Plugin development guide](/docs/PLUGINS_DEV.md). \ No newline at end of file diff --git a/front/plugins/db_cleanup/script.py b/front/plugins/db_cleanup/script.py index 2365cf45..2979b0fb 100755 --- a/front/plugins/db_cleanup/script.py +++ b/front/plugins/db_cleanup/script.py @@ -32,7 +32,7 @@ def main(): parser.add_argument('pluginskeephistory', action="store", help="TBC") parser.add_argument('hourstokeepnewdevice', action="store", help="TBC") parser.add_argument('daystokeepevents', action="store", help="TBC") - parser.add_argument('pholuskeepdays', action="store", help="TBC") + parser.add_argument('pholuskeepdays', action="store", help="TBC") # unused values = parser.parse_args() diff --git a/front/plugins/internet_ip/config.json b/front/plugins/internet_ip/config.json index 8adacb53..74a82c96 100755 --- a/front/plugins/internet_ip/config.json +++ b/front/plugins/internet_ip/config.json @@ -258,6 +258,28 @@ } ] }, + { + "function": "RETRIES", + "type": "integer", + "default_value": 3, + "options": [], + "localized": [ + "name", + "description" + ], + "name": [ + { + "language_code": "en_us", + "string": "Retries" + } + ], + "description": [ + { + "language_code": "en_us", + "string": "Number of retries before Internet is marked as unreachable. Exponential backoff strategy is used between tries (1s - 1st retry, 2s - 2nd retry, etc)." + } + ] + }, { "function": "WATCH", "type": "text.multiselect", @@ -434,6 +456,21 @@ "string" : "Response" } ] + }, + { + "column": "Watched_Value3", + "css_classes": "col-sm-2", + "show": true, + "type": "label", + "default_value":"", + "options": [], + "localized": ["name"], + "name":[ + { + "language_code": "en_us", + "string" : "Retries needed" + } + ] }, { "column": "Dummy", diff --git a/front/plugins/internet_ip/script.py b/front/plugins/internet_ip/script.py index d02e5763..adae2aa4 100755 --- a/front/plugins/internet_ip/script.py +++ b/front/plugins/internet_ip/script.py @@ -1,6 +1,7 @@ #!/usr/bin/env python import os +import time import pathlib import argparse import sys @@ -29,6 +30,8 @@ RESULT_FILE = os.path.join(CUR_PATH, 'last_result.log') pluginName = 'INTRNT' +no_internet_ip = '0.0.0.0' + def main(): mylog('verbose', [f'[{pluginName}] In script']) @@ -45,13 +48,20 @@ def main(): mylog('verbose', [f'[{pluginName}] INTRNT_DIG_GET_IP_ARG: ', DIG_GET_IP_ARG]) - # Decode the base64-encoded value to get the actual value in ASCII format. - # DIG_GET_IP_ARG = base64.b64decode(DIG_GET_IP_ARG).decode('ascii') - - # mylog('verbose', [f'[{pluginName}] DIG_GET_IP_ARG resolved: {DIG_GET_IP_ARG} ']) + # perform the new IP lookup N times specified by the INTRNT_TRIES setting + new_internet_IP = "" + INTRNT_RETRIES = get_setting_value("INTRNT_RETRIES") + tries_needed = 0 - # perform the new IP lookup - new_internet_IP, cmd_output = check_internet_IP( PREV_IP, DIG_GET_IP_ARG) + for i in range(INTRNT_RETRIES + 1): + + new_internet_IP, cmd_output = check_internet_IP( PREV_IP, DIG_GET_IP_ARG) + + if new_internet_IP == no_internet_ip: + time.sleep(1*i) # Exponential backoff strategy + else: + tries_needed = i + break plugin_objects = Plugin_Objects(RESULT_FILE) @@ -60,7 +70,7 @@ def main(): secondaryId = new_internet_IP, # IP Address watched1 = f'Previous IP: {PREV_IP}', watched2 = cmd_output.replace('\n',''), - watched3 = '', + watched3 = tries_needed, watched4 = '', extra = f'Previous IP: {PREV_IP}', foreignKey = 'Internet') @@ -84,7 +94,7 @@ def check_internet_IP ( PREV_IP, DIG_GET_IP_ARG ): mylog('verbose', [f'[{pluginName}] Current internet_IP : {internet_IP}']) # Check previously stored IP - previous_IP = '0.0.0.0' + previous_IP = no_internet_ip if PREV_IP is not None and len(PREV_IP) > 0 : previous_IP = PREV_IP @@ -116,7 +126,7 @@ def get_internet_IP (DIG_GET_IP_ARG): # Handle invalid response if IP == '': - IP = '0.0.0.0' + IP = no_internet_ip return IP, cmd_output diff --git a/front/settings.php b/front/settings.php index fda8af61..9ec8fad7 100755 --- a/front/settings.php +++ b/front/settings.php @@ -592,8 +592,10 @@ while ($row = $result -> fetchArray (SQLITE3_ASSOC)) { } - + // init finished + setupSmoothScrolling() + hideSpinner() } @@ -840,6 +842,8 @@ while ($row = $result -> fetchArray (SQLITE3_ASSOC)) { // ----------------------------------------------------------------------------- function handleLoadingDialog() { + + // check if config file has been updated $.get('api/app_state.json?nocache=' + Date.now(), function(appState) { fileModificationTime = ; @@ -865,7 +869,8 @@ while ($row = $result -> fetchArray (SQLITE3_ASSOC)) { // check if the app is initialized and hide the spinner if(isAppInitialized()) { - hideSpinner() + // init page + getData() // reload page if outdated information might be displayed if(secondsSincePageLoad() > 3) @@ -892,8 +897,6 @@ while ($row = $result -> fetchArray (SQLITE3_ASSOC)) { } - getData() -