Skip to content

Latest commit

 

History

History
executable file
·
107 lines (81 loc) · 10.8 KB

README.md

File metadata and controls

executable file
·
107 lines (81 loc) · 10.8 KB
Raw

🔌 Plugins

NetAlertX supports additional plugins to extend its functionality, each with its own settings and options. Plugins can be loaded via the General -> LOADED_PLUGINS setting. For custom plugin development, refer to the Plugin development guide.

Note

Please check this Plugins debugging guide and the corresponding Plugin documentation in the below table if you are facing issues.

⚡ Quick start

Tip

You can load additional Plugins via the General -> LOADED_PLUGINS setting.

  1. Pick your 🔍 dev scanner plugin (e.g. ARPSCAN or NMAPDEV), or import devices into the application with an 📥 importer plugin. (See ✅Enabling plugins below)
  2. Pick a ▶️ publisher plugin, if you want to send notifications. If you don't see a publisher you'd like to use, look at the 📚_publisher_apprise plugin which is a proxy for over 80 notification services.
  3. Setup your Network topology diagram
  4. Fine-tune Notifications
  5. Backup your setup
  6. Contribute and Create custom plugins

📑 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 at least some device-detecting plugins enabled, such as ARPSCAN or NMAPDEV.

ID Type Description Features Required Data source Detailed docs
APPRISE ▶️ Apprise notification proxy Script _publisher_apprise
ARPSCAN 🔍 ARP-scan on current network Script arp_scan
AVAHISCAN ♻ Avahi (mDNS-based) name resolution Script avahi_scan
CSVBCKP ⚙ CSV devices backup Script csv_backup
DBCLNP ⚙ Database cleanup Yes* Script db_cleanup
DDNS ⚙ DDNS update Script ddns_update
DHCPLSS 🔍/📥 Import devices from DHCP leases Script dhcp_leases
DHCPSRVS ♻ DHCP servers Script dhcp_servers
INTRNT 🔍 Internet IP scanner Script internet_ip
INTRSPD ♻ Internet speed test Script internet_speedtest
MAINT ⚙ Maintenance of logs, etc. Script maintenance
MQTT ▶️ MQTT for synching to Home Assistant Script _publisher_mqtt
NBTSCAN ♻ Nbtscan (NetBIOS-based) name resolution Script nbtscan_scan
NEWDEV ⚙ New device template Yes Template newdev_template
NMAP ♻ Nmap port scanning & discovery Script nmap_scan
NMAPDEV 🔍 Nmap dev scan on current network Script nmap_dev_scan
NSLOOKUP ♻ NSLookup (DNS-based) name resolution Script nslookup_scan
NTFPRCS ⚙ Notification processing Yes Template notification_processing
NTFY ▶️ NTFY notifications Script _publisher_ntfy
OMDSDN 📥 OMADA TP-Link import 🖧 🔄 Script omada_sdn_imp
PHOLUS ♻ Pholus name resolution Script pholus_scan
PIHOLE 🔍/📥 Pi-hole device import & sync SQLite DB pihole_scan
PUSHSAFER ▶️ Pushsafer notifications Script _publisher_pushsafer
PUSHOVER ▶️ Pushover notifications Script _publisher_pushover
SETPWD ⚙ Set password Yes Template set_password
SMTP ▶️ Email notifications Script _publisher_email
SNMPDSC 🔍/📥 SNMP device import & sync Script snmp_discovery
SYNC 🔍/⚙/📥 Sync & import from NetAlertX instances 🖧 🔄 Script sync
TELEGRAM ▶️ Telegram notifications Script _publisher_telegram
UNDIS 🔍/📥 Create dummy devices Script undiscoverables
UNFIMP 🔍/📥 UniFi device import & sync 🖧 Script unifi_import
VNDRPDT ⚙ Vendor database update Script vendor_update
WEBHOOK ▶️ Webhook notifications Script _publisher_webhook
WEBMON ♻ Website down monitoring Script 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.

⌚It's recommended to use the same schedule interval for all plugins responsible for discovering new devices.

Plugin types

Plugin type Icon Description When to run Required Data source ?
publisher ▶️ Sending notifications to services. on_notification ✖ Script
dev scanner 🔍 Create devices in the app, manages online/offline device status. schedule ✖ Script / SQLite DB
importer 📥 Importing devices from another service. schedule ✖ Script / SQLite DB
system ⚙ Providing core system functionality. schedule / always on ✖/✔ Script / Template
other ♻ Other scanners, e.g. for name resolution misc ✖ Script / Template

Features

Icon Description
🖧 Auto-imports the network topology diagram
🔄 Has the option to sync some data back into the plugin source

✅Enabling plugins

Plugins can be enabled via Settings, and can be disabled as needed.

  1. Research which plugin you'd like to use and load the required plugins in Settings via the LOADED_PLUGINS setting.
  2. Save the changes and review the Settings of the newly loaded plugins.
  3. Change the <prefix>_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 <prefix>_RUN Setting to disabled if you want to disable the plugin, but keep the settings
  2. 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)
  3. 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.

🆕 Developing new custom plugins

If you want to develop a custom plugin, please read this Plugin development guide.