vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2025-12-06 17:15:38 -08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
jokob-sk
2025-04-06 09:38:23 +10:00
parent 3ccb165658
commit 40e090c5c6
8 changed files with 41 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/NAME_RESOLUTION.md
View File

@@ -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.

54
docs/PLUGINS.md
View File

@@ -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.

14
docs/WEB_UI_PORT_DEBUG.md
View File

@@ -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://<your rpi IP>/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`

4
docs/WORKFLOWS_DEBUGGING.md
View File

@@ -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

BIN
docs/img/PLUGINS/loaded_plugins_setting.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 77 KiB

BIN
docs/img/WORKFLOWS/workflows_app_events_search.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 166 KiB

BIN
docs/img/WORKFLOWS/workflows_logs_search.png Executable file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 164 KiB

4
front/plugins/omada_sdn_imp/README.md
View File

@@ -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