diff --git a/docs/NAME_RESOLUTION.md b/docs/NAME_RESOLUTION.md index 19cb103d..dd8a5fec 100755 --- a/docs/NAME_RESOLUTION.md +++ b/docs/NAME_RESOLUTION.md @@ -1,4 +1,4 @@ -# NAME RESOLUTION +# Device Name Resolution Name resolution in NetAlertX relies on multiple plugins to resolve device names from IP addresses. If you are seeing `(name not found)` as device names, follow these steps to diagnose and fix the issue. diff --git a/docs/PLUGINS.md b/docs/PLUGINS.md index 09c8aac6..adc986a4 100755 --- a/docs/PLUGINS.md +++ b/docs/PLUGINS.md @@ -8,23 +8,41 @@ NetAlertX supports additional plugins to extend its functionality, each with its ## ⚑ Quick start > [!TIP] -> You can load additional Plugins via the General -> `LOADED_PLUGINS` setting. +> You can load additional Plugins via the General -> `LOADED_PLUGINS` setting. You need to save the settings for the new plugins to load (cahce/page relaod may be necessary). +> ![Loaded plugins settings](./img/PLUGINS/loaded_plugins_setting.png) -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) +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](/front/plugins/_publisher_apprise/) plugin which is a proxy for over 80 notification services. 3. Setup your [Network topology diagram](./NETWORK_TREE.md) 4. Fine-tune [Notifications](./NOTIFICATIONS.md) -5. [Backup your setup](./BACKUPS.md) -6. Contribute and [Create custom plugins](./PLUGINS_DEV.md) +5. Setup [Workflows](./WORKFLOWS.md) +6. [Backup your setup](./BACKUPS.md) +7. Contribute and [Create custom plugins](./PLUGINS_DEV.md) -## πŸ“‘ Available Plugins +## Plugin types + +| Plugin type | Icon | Description | When to run | Required | Data source [?](./PLUGINS_DEV.md) | +| -------------- | ---- | ---------------------------------------------------------------- | ----------------------------------- | -------- | ------------------------------------- | +| publisher | ▢️ | Sending notifications to services. | `on_notification` | βœ– | Script | +| dev scanner | πŸ” | Create devices in the app, manages online/offline device status. | `schedule` | βœ– | Script / SQLite DB | +| name discovery | πŸ†Ž | Discovers names of devices via various protocols. | `before_name_updates`, `schedule` | βœ– | Script | +| importer | πŸ“₯ | Importing devices from another service. | `schedule` | βœ– | Script / SQLite DB | +| system | βš™ | Providing core system functionality. | `schedule` / always on | βœ–/βœ” | Script / Template | +| other | β™» | Other plugins | misc | βœ– | Script / Template | + +## Features + +| Icon | Description | +| ---- | ------------------------------------------------------------ | +| πŸ–§ | Auto-imports the network topology diagram | +| πŸ”„ | Has the option to sync some data back into the plugin source | + + +## 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`. -> [!NOTE] -> See tables below for a description of what the icons in the below Plugins table mean. - | ID | Type | Description | Features | Required | Data source | Detailed docs | |---------------|---------|--------------------------------------------|----------|----------|--------------|---------------------------------------------------------------------| @@ -75,27 +93,9 @@ Device-detecting plugins insert values into the `CurrentScan` database table. T > ❌ marked for removal > ⌚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 [?](./PLUGINS_DEV.md) | -| -------------- | ---- | ---------------------------------------------------------------- | ----------------------------------- | -------- | ------------------------------------- | -| publisher | ▢️ | Sending notifications to services. | `on_notification` | βœ– | Script | -| dev scanner | πŸ” | Create devices in the app, manages online/offline device status. | `schedule` | βœ– | Script / SQLite DB | -| name discovery | πŸ†Ž | Discovers names of devices via various protocols. | `before_name_updates`, `schedule` | βœ– | Script | -| importer | πŸ“₯ | Importing devices from another service. | `schedule` | βœ– | Script / SQLite DB | -| system | βš™ | Providing core system functionality. | `schedule` / always on | βœ–/βœ” | Script / Template | -| other | β™» | Other plugins | 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 +## Enabling plugins Plugins can be enabled via Settings, and can be disabled as needed. diff --git a/docs/WEB_UI_PORT_DEBUG.md b/docs/WEB_UI_PORT_DEBUG.md index 36b6af59..a1349f2a 100755 --- a/docs/WEB_UI_PORT_DEBUG.md +++ b/docs/WEB_UI_PORT_DEBUG.md @@ -2,15 +2,15 @@ ## 1. Port conflicts -When opening an issue please: +When opening an issue or debugging: 1. Include a screenshot of what you see when accessing `HTTP:///20211` (or your custom port) 1. [Follow steps 1, 2, 3, 4 on this page](./DEBUG_TIPS.md) 1. Execute the following in the container to see the processes and their ports and submit a screenshot of the result: - 1. `sudo apk add lsof` - 1. `sudo lsof -i` -1. Try running the `nginx` command in the container - 1. if you get `nginx: [emerg] bind() to 0.0.0.0:20211 failed (98: Address in use)` try using a different port number + - `sudo apk add lsof` + - `sudo lsof -i` +1. Try running the `nginx` command in the container: + - if you get `nginx: [emerg] bind() to 0.0.0.0:20211 failed (98: Address in use)` try using a different port number ![lsof ports](./img/WEB_UI_PORT_DEBUG/container_port.png) @@ -23,7 +23,7 @@ Check for browser console (F12 browser dev console) errors + check different bro Refresh the browser cache (usually shoft + refresh), try a private window, or different browsers. Please also refresh the app cache by clicking the πŸ”ƒ (reload) button in the header of the application. -## 4. Disable proxy +## 4. Disable proxies If you have any reverse proxy or similar, try disabling it. @@ -37,7 +37,7 @@ If you haven't, post your docker compose/run command. ## 7. Check for errors in your PHP/NGINX error logs -In the container execute: +In the container execute and investigate: `cat /var/log/nginx/error.log` diff --git a/docs/WORKFLOWS_DEBUGGING.md b/docs/WORKFLOWS_DEBUGGING.md index dbcdf85d..79eec5ba 100755 --- a/docs/WORKFLOWS_DEBUGGING.md +++ b/docs/WORKFLOWS_DEBUGGING.md @@ -12,10 +12,14 @@ Workflows are triggered by various events. These events are captured and listed If an event doesn't trigger a workflow as expected, check the _App Events_ section for the event. You can filter these by the ID of the device (`devMAC` or `devGUID`). +![App events search](./img/WORKFLOWS/workflows_app_events_search.png) + Once you find the _Event Guid_ and _Object GUID_, use them to find relevant debug entries. Navigate to _Mainetenace -> Logs_ where you can filter the logs based on the _Event or Object GUID_. +![Log events search](./img/WORKFLOWS/workflows_logs_search.png) + Below you can find some example `app.log` entries that will help you understand why a Workflow was or was not triggered. ```bash diff --git a/docs/img/PLUGINS/loaded_plugins_setting.png b/docs/img/PLUGINS/loaded_plugins_setting.png new file mode 100755 index 00000000..6b3fd998 Binary files /dev/null and b/docs/img/PLUGINS/loaded_plugins_setting.png differ diff --git a/docs/img/WORKFLOWS/workflows_app_events_search.png b/docs/img/WORKFLOWS/workflows_app_events_search.png new file mode 100755 index 00000000..4e0300d0 Binary files /dev/null and b/docs/img/WORKFLOWS/workflows_app_events_search.png differ diff --git a/docs/img/WORKFLOWS/workflows_logs_search.png b/docs/img/WORKFLOWS/workflows_logs_search.png new file mode 100755 index 00000000..c19d431e Binary files /dev/null and b/docs/img/WORKFLOWS/workflows_logs_search.png differ diff --git a/front/plugins/omada_sdn_imp/README.md b/front/plugins/omada_sdn_imp/README.md index e420a004..90c29ac8 100755 --- a/front/plugins/omada_sdn_imp/README.md +++ b/front/plugins/omada_sdn_imp/README.md @@ -41,8 +41,8 @@ The OMADA SDN plugin aims at synchronizing data between NetAlertX and a TPLINK O OMADA SDN limitation fixed by the plugin: 0. OMADA SDN can't use DNS for names and keep using MAC ref: https://community.tp-link.com/en/business/forum/topic/503782 - when you use an OMADA user Role = Administrator, the plugin will attempt to fix OMADA's shortcoming and populat the NAME field from NetAlertX (from DNS/DHCP/...) -![OMADA SDN account page](Oamadaomada_sdn_imp.png) -- +![OMADA SDN account page](omada_account_sample.png) + can not fix some of tplinks OMADA SDN own limitations/bugs: 1. OMADA SDN switches uplinks/downlinks is broken if the default router is not an OMADA native device