mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2026-03-31 07:12:23 -07:00
Merge remote-tracking branch 'upstream/main' into add-caddy-and-authentik-sso-documentation
This commit is contained in:
luckylinux
@@ -18,7 +18,6 @@ Only specific, pre-approved log files can be purged for security and stability r
|
||||
|
||||
```
|
||||
app.log
|
||||
app_front.log
|
||||
IP_changes.log
|
||||
stdout.log
|
||||
stderr.log
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# [Deprecated] API endpoints
|
||||
|
||||
> [!WARNING]
|
||||
> Some of these endpoints will be deprecated soon. Please refere to the new [API](API.md) endpoints docs for details on the new API layer.
|
||||
> [!WARNING]
|
||||
> Some of these endpoints will be deprecated soon. Please refere to the new [API](API.md) endpoints docs for details on the new API layer.
|
||||
|
||||
NetAlertX comes with a couple of API endpoints. All requests need to be authorized (executed in a logged in browser session) or you have to pass the value of the `API_TOKEN` settings as authorization bearer, for example:
|
||||
|
||||
@@ -56,7 +56,7 @@ See also: [Debugging GraphQL issues](./DEBUG_API_SERVER.md)
|
||||
|
||||
### `curl` Command
|
||||
|
||||
You can use the following `curl` command to execute the query.
|
||||
You can use the following `curl` command to execute the query.
|
||||
|
||||
```sh
|
||||
curl 'http://host:GRAPHQL_PORT/graphql' -X POST -H 'Authorization: Bearer API_TOKEN' -H 'Content-Type: application/json' --data '{
|
||||
@@ -127,9 +127,9 @@ The response will be in JSON format, similar to the following:
|
||||
}
|
||||
```
|
||||
|
||||
## API Endpoint: JSON files
|
||||
## API Endpoint: JSON files
|
||||
|
||||
This API endpoint retrieves static files, that are periodically updated.
|
||||
This API endpoint retrieves static files, that are periodically updated.
|
||||
|
||||
- Endpoint URL: `php/server/query_json.php?file=<file name>`
|
||||
- Host: `same as front end (web ui)`
|
||||
@@ -147,18 +147,18 @@ In the container, these files are located under the API directory (default: `/tm
|
||||
|
||||
You can access the following files:
|
||||
|
||||
| File name | Description |
|
||||
|----------------------|----------------------|
|
||||
| File name | Description |
|
||||
|----------------------|----------------------|
|
||||
| `notification_json_final.json` | The json version of the last notification (e.g. used for webhooks - [sample JSON](https://github.com/jokob-sk/NetAlertX/blob/main/front/report_templates/webhook_json_sample.json)). |
|
||||
| `table_devices.json` | All of the available Devices detected by the app. |
|
||||
| `table_devices.json` | All of the available Devices detected by the app. |
|
||||
| `table_plugins_events.json` | The list of the unprocessed (pending) notification events (plugins_events DB table). |
|
||||
| `table_plugins_history.json` | The list of notification events history. |
|
||||
| `table_plugins_objects.json` | The content of the plugins_objects table. Find more info on the [Plugin system here](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md)|
|
||||
| `language_strings.json` | The content of the language_strings table, which in turn is loaded from the plugins `config.json` definitions. |
|
||||
| `table_plugins_history.json` | The list of notification events history. |
|
||||
| `table_plugins_objects.json` | The content of the plugins_objects table. Find more info on the [Plugin system here](https://docs.netalertx.com/PLUGINS)|
|
||||
| `language_strings.json` | The content of the language_strings table, which in turn is loaded from the plugins `config.json` definitions. |
|
||||
| `table_custom_endpoint.json` | A custom endpoint generated by the SQL query specified by the `API_CUSTOM_SQL` setting. |
|
||||
| `table_settings.json` | The content of the settings table. |
|
||||
| `app_state.json` | Contains the current application state. |
|
||||
|
||||
|
||||
|
||||
### JSON Data format
|
||||
|
||||
@@ -169,11 +169,11 @@ The endpoints starting with the `table_` prefix contain most, if not all, data c
|
||||
"data": [
|
||||
{
|
||||
"db_column_name": "data",
|
||||
"db_column_name2": "data2"
|
||||
},
|
||||
"db_column_name2": "data2"
|
||||
},
|
||||
{
|
||||
"db_column_name": "data3",
|
||||
"db_column_name2": "data4"
|
||||
"db_column_name2": "data4"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -201,7 +201,7 @@ Example JSON of the `table_devices.json` endpoint with two Devices (database row
|
||||
"devParentMAC": "",
|
||||
"devParentPort": "",
|
||||
"devIcon": "globe"
|
||||
},
|
||||
},
|
||||
{
|
||||
"devMac": "a4:8f:ff:aa:ba:1f",
|
||||
"devName": "Net - USG",
|
||||
@@ -332,7 +332,7 @@ Grafana template sample: [Download json](./samples/API/Grafana_Dashboard.json)
|
||||
|
||||
## API Endpoint: /log files
|
||||
|
||||
This API endpoint retrieves files from the `/tmp/log` folder.
|
||||
This API endpoint retrieves files from the `/tmp/log` folder.
|
||||
|
||||
- Endpoint URL: `php/server/query_logs.php?file=<file name>`
|
||||
- Host: `same as front end (web ui)`
|
||||
@@ -357,7 +357,7 @@ This API endpoint retrieves files from the `/tmp/log` folder.
|
||||
|
||||
## API Endpoint: /config files
|
||||
|
||||
To retrieve files from the `/data/config` folder.
|
||||
To retrieve files from the `/data/config` folder.
|
||||
|
||||
- Endpoint URL: `php/server/query_config.php?file=<file name>`
|
||||
- Host: `same as front end (web ui)`
|
||||
|
||||
@@ -118,11 +118,14 @@ curl -X DELETE "http://<server_ip>:<GRAPHQL_PORT>/sessions/delete" \
|
||||
```
|
||||
#### `curl` Example
|
||||
|
||||
**get sessions for mac**
|
||||
|
||||
```bash
|
||||
curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/list?mac=AA:BB:CC:DD:EE:FF&start_date=2025-08-01&end_date=2025-08-21" \
|
||||
-H "Authorization: Bearer <API_TOKEN>" \
|
||||
-H "Accept: application/json"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Calendar View of Sessions
|
||||
|
||||
78
docs/API_SSE.md
Normal file
78
docs/API_SSE.md
Normal file
@@ -0,0 +1,78 @@
|
||||
# SSE (Server-Sent Events)
|
||||
|
||||
Real-time app state updates via Server-Sent Events. Reduces server load ~95% vs polling.
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Endpoint | Method | Purpose |
|
||||
|----------|--------|---------|
|
||||
| `/sse/state` | GET | Stream state updates (requires Bearer token) |
|
||||
| `/sse/stats` | GET | Debug: connected clients, queued events |
|
||||
|
||||
## Usage
|
||||
|
||||
### Connect to SSE Stream
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
|
||||
http://localhost:5000/sse/state
|
||||
```
|
||||
|
||||
### Check Connection Stats
|
||||
```bash
|
||||
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
|
||||
http://localhost:5000/sse/stats
|
||||
```
|
||||
|
||||
## Event Types
|
||||
|
||||
- `state_update` - App state changed (e.g., "Scanning", "Processing")
|
||||
- `unread_notifications_count_update` - Number of unread notifications changed (count: int)
|
||||
|
||||
## Backend Integration
|
||||
|
||||
Broadcasts automatically triggered in `app_state.py` via `broadcast_state_update()`:
|
||||
|
||||
```python
|
||||
from api_server.sse_broadcast import broadcast_state_update
|
||||
|
||||
# Called on every state change - no additional code needed
|
||||
broadcast_state_update(current_state="Scanning", settings_imported=time.time())
|
||||
```
|
||||
|
||||
## Frontend Integration
|
||||
|
||||
Auto-enabled via `sse_manager.js`:
|
||||
|
||||
```javascript
|
||||
// In browser console:
|
||||
netAlertXStateManager.getStats().then(stats => {
|
||||
console.log("Connected clients:", stats.connected_clients);
|
||||
});
|
||||
```
|
||||
|
||||
## Fallback Behavior
|
||||
|
||||
- If SSE fails after 3 attempts, automatically switches to polling
|
||||
- Polling starts at 1s, backs off to 30s max
|
||||
- No user-visible difference in functionality
|
||||
|
||||
## Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `server/api_server/sse_endpoint.py` | SSE endpoints & event queue |
|
||||
| `server/api_server/sse_broadcast.py` | Broadcast helper functions |
|
||||
| `front/js/sse_manager.js` | Client-side SSE connection manager |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Connection refused | Check backend running, API token correct |
|
||||
| No events received | Verify `broadcast_state_update()` is called on state changes |
|
||||
| High memory | Events not processed fast enough, check client logs |
|
||||
| Using polling instead of SSE | Normal fallback - check browser console for errors |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
## Authelia support
|
||||
|
||||
> [!WARNING]
|
||||
>
|
||||
> This is community contributed content and work in progress. Contributions are welcome.
|
||||
> [!NOTE]
|
||||
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
|
||||
|
||||
|
||||
```yaml
|
||||
theme: dark
|
||||
@@ -274,4 +274,4 @@ notifier:
|
||||
subject: "[Authelia] {title}"
|
||||
startup_check_address: postmaster@MYOTHERDOMAIN.LTD
|
||||
|
||||
```
|
||||
```
|
||||
|
||||
1
docs/CNAME
Normal file
1
docs/CNAME
Normal file
@@ -0,0 +1 @@
|
||||
docs.netalertx.com
|
||||
@@ -1,15 +1,21 @@
|
||||
# Community Guides
|
||||
|
||||
Use the official installation guides at first and use community content as supplementary material. Open an issue or PR if you'd like to add your link to the list 🙏 (Ordered by last update time)
|
||||
> [!NOTE]
|
||||
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
|
||||
|
||||
|
||||
Use the official installation guides at first and use community content as supplementary material. (Ordered by last update time)
|
||||
|
||||
- ▶ [Discover & Monitor Your Network with This Self-Hosted Open Source Tool - Lawrence Systems](https://www.youtube.com/watch?v=R3b5cxLZMpo) (June 2025)
|
||||
- ▶ [Home Lab Network Monitoring - Scotti-BYTE Enterprise Consulting Services](https://www.youtube.com/watch?v=0DryhzrQSJA) (July 2024)
|
||||
- 📄 [How to Install NetAlertX on Your Synology NAS - Marius hosting](https://mariushosting.com/how-to-install-pi-alert-on-your-synology-nas/) (Updated frequently)
|
||||
- 📄 [Using the PiAlert Network Security Scanner on a Raspberry Pi - PiMyLifeUp](https://pimylifeup.com/raspberry-pi-pialert/)
|
||||
- ▶ [How to Setup Pi.Alert on Your Synology NAS - Digital Aloha](https://www.youtube.com/watch?v=M4YhpuRFaUg)
|
||||
- ▶ [How to Setup Pi.Alert on Your Synology NAS - Digital Aloha](https://www.youtube.com/watch?v=M4YhpuRFaUg)
|
||||
- 📄 [防蹭网神器，网络安全助手 | 极空间部署网络扫描和通知系统『NetAlertX』](https://blog.csdn.net/qq_63499861/article/details/141105273)
|
||||
- 📄 [시놀/헤놀에서 네트워크 스캐너 Pi.Alert Docker로 설치 및 사용하기](https://blog.dalso.org/article/%EC%8B%9C%EB%86%80-%ED%97%A4%EB%86%80%EC%97%90%EC%84%9C-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-%EC%8A%A4%EC%BA%90%EB%84%88-pi-alert-docker%EB%A1%9C-%EC%84%A4%EC%B9%98-%EB%B0%8F-%EC%82%AC%EC%9A%A9) (July 2023)
|
||||
- 📄 [网络入侵探测器Pi.Alert (Chinese)](https://codeantenna.com/a/VgUvIAjZ7J) (May 2023)
|
||||
- ▶ [Pi.Alert auf Synology & Docker by - Jürgen Barth](https://www.youtube.com/watch?v=-ouvA2UNu-A) (March 2023)
|
||||
- ▶ [Top Docker Container for Home Server Security - VirtualizationHowto](https://www.youtube.com/watch?v=tY-w-enLF6Q) (March 2023)
|
||||
- ▶ [Pi.Alert or WatchYourLAN can alert you to unknown devices appearing on your WiFi or LAN network - Danie van der Merwe](https://www.youtube.com/watch?v=v6an9QG2xF0) (November 2022)
|
||||
|
||||
|
||||
|
||||
@@ -13,31 +13,6 @@ This functionality allows you to define **custom properties** for devices, which
|
||||
|
||||
---
|
||||
|
||||
## Defining Custom Properties
|
||||
|
||||
Custom properties are structured as a list of objects, where each property includes the following fields:
|
||||
|
||||
| Field | Description |
|
||||
|--------------------|-----------------------------------------------------------------------------|
|
||||
| `CUSTPROP_icon` | The icon (Base64-encoded HTML) displayed for the property. |
|
||||
| `CUSTPROP_type` | The action type (e.g., `show_notes`, `link`, `delete_dev`). |
|
||||
| `CUSTPROP_name` | A short name or title for the property. |
|
||||
| `CUSTPROP_args` | Arguments for the action (e.g., URL or modal text). |
|
||||
| `CUSTPROP_notes` | Additional notes or details displayed when applicable. |
|
||||
| `CUSTPROP_show` | A boolean to control visibility (`true` to show on the listing page). |
|
||||
|
||||
---
|
||||
|
||||
## Available Action Types
|
||||
|
||||
- **Show Notes**: Displays a modal with a title and additional notes.
|
||||
- **Example**: Show firmware details or custom messages.
|
||||
- **Link**: Redirects to a specified URL in the current browser tab. (**Arguments** Needs to contain the full URL.)
|
||||
- **Link (New Tab)**: Opens a specified URL in a new browser tab. (**Arguments** Needs to contain the full URL.)
|
||||
- **Delete Device**: Deletes the device using its MAC address.
|
||||
- **Run Plugin**: Placeholder for executing custom plugins (not implemented yet).
|
||||
|
||||
---
|
||||
|
||||
## Usage on the Device Listing Page
|
||||
|
||||
@@ -74,12 +49,39 @@ Visible properties (`CUSTPROP_show: true`) are displayed as interactive icons in
|
||||
3. **Device Removal**:
|
||||
- Enable device removal functionality using `CUSTPROP_type: delete_dev`.
|
||||
|
||||
---
|
||||
|
||||
## Defining Custom Properties
|
||||
|
||||
Custom properties are structured as a list of objects, where each property includes the following fields:
|
||||
|
||||
| Field | Description |
|
||||
|--------------------|-----------------------------------------------------------------------------|
|
||||
| `CUSTPROP_icon` | The icon (Base64-encoded HTML) displayed for the property. |
|
||||
| `CUSTPROP_type` | The action type (e.g., `show_notes`, `link`, `delete_dev`). |
|
||||
| `CUSTPROP_name` | A short name or title for the property. |
|
||||
| `CUSTPROP_args` | Arguments for the action (e.g., URL or modal text). |
|
||||
| `CUSTPROP_notes` | Additional notes or details displayed when applicable. |
|
||||
| `CUSTPROP_show` | A boolean to control visibility (`true` to show on the listing page). |
|
||||
|
||||
---
|
||||
|
||||
## Available Action Types
|
||||
|
||||
- **Show Notes**: Displays a modal with a title and additional notes.
|
||||
- **Example**: Show firmware details or custom messages.
|
||||
- **Link**: Redirects to a specified URL in the current browser tab. (**Arguments** Needs to contain the full URL.)
|
||||
- **Link (New Tab)**: Opens a specified URL in a new browser tab. (**Arguments** Needs to contain the full URL.)
|
||||
- **Delete Device**: Deletes the device using its MAC address.
|
||||
- **Run Plugin**: Placeholder for executing custom plugins (not implemented yet).
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Plugin Functionality**: The `run_plugin` action type is currently not implemented and will show an alert if used.
|
||||
- **Custom Icons (Experimental 🧪)**: Use Base64-encoded HTML to provide custom icons for each property. You can add your icons in Setttings via the `CUSTPROP_icon` settings
|
||||
- **Custom Icons (Experimental 🧪)**: Use Base64-encoded HTML to provide custom icons for each property. You can add your icons in Setttings via the `CUSTPROP_icon` settings
|
||||
- **Visibility Control**: Only properties with `CUSTPROP_show: true` will appear on the listing page.
|
||||
|
||||
This feature provides a flexible way to enhance device management and display with interactive elements tailored to your needs.
|
||||
|
||||
@@ -26,7 +26,7 @@ The database and device structure may change with new releases. When using the C
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> The file containing a list of Devices including the Network relationships between Network Nodes and connected devices. You can also trigger this by acessing this URL: `<server>:20211/php/server/devices.php?action=ExportCSV` or via the `CSV Backup` plugin. (💡 You can schedule this)
|
||||
> The file containing a list of Devices including the Network relationships between Network Nodes and connected devices. You can also trigger this with the `CSV Backup` plugin. (💡 You can schedule this)
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@ The Main Info section is where most of the device identifiable information is st
|
||||
|
||||
- **MAC**: MAC addres of the device. Not editable, unless creating a new dummy device.
|
||||
- **Last IP**: IP addres of the device. Not editable, unless creating a new dummy device.
|
||||
- **Name**: Friendly device name. Autodetected via various 🆎 Name discovery [plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). The app attaches `(IP match)` if the name is discovered via an IP match and not MAC match which could mean the name could be incorrect as IPs might change.
|
||||
- **Name**: Friendly device name. Autodetected via various 🆎 Name discovery [plugins](https://docs.netalertx.com/PLUGINS). The app attaches `(IP match)` if the name is discovered via an IP match and not MAC match which could mean the name could be incorrect as IPs might change.
|
||||
- **Icon**: Partially autodetected. Select an existing or [add a custom icon](./ICONS.md). You can also auto-apply the same icon on all devices of the same type.
|
||||
- **Owner**: Device owner (The list is self-populated with existing owners and you can add custom values).
|
||||
- **Type**: Select a device type from the dropdown list (`Smartphone`, `Tablet`,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# NetAlertX and Docker Compose
|
||||
|
||||
> [!WARNING]
|
||||
> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
|
||||
> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://docs.netalertx.com/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
|
||||
|
||||
Great care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system.Good care is taken to ensure NetAlertX meets the needs of everyone while being flexible enough for anyone. This document outlines how you can configure your docker-compose. There are many settings, so we recommend using the Baseline Docker Compose as-is, or modifying it for your system.
|
||||
|
||||
@@ -69,6 +69,8 @@ services:
|
||||
PORT: ${PORT:-20211} # Application port
|
||||
GRAPHQL_PORT: ${GRAPHQL_PORT:-20212} # GraphQL API port (passed into APP_CONF_OVERRIDE at runtime)
|
||||
# NETALERTX_DEBUG: ${NETALERTX_DEBUG:-0} # 0=kill all services and restart if any dies. 1 keeps running dead services.
|
||||
# PUID: 20211 # Runtime PUID override, set to 0 to run as root
|
||||
# PGID: 20211 # Runtime PGID override
|
||||
|
||||
# Resource limits to prevent resource exhaustion
|
||||
mem_limit: 2048m # Maximum memory usage
|
||||
@@ -171,10 +173,6 @@ Now, any files created by NetAlertX in `/data/config` will appear in your `/loca
|
||||
|
||||
This same method works for mounting other things, like custom plugins or enterprise NGINX files, as shown in the commented-out examples in the baseline file.
|
||||
|
||||
## Example Configuration Summaries
|
||||
|
||||
Here are the essential modifications for common alternative setups.
|
||||
|
||||
### Example 2: External `.env` File for Paths
|
||||
|
||||
This method is useful for keeping your paths and other settings separate from your main compose file, making it more portable.
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
# NetAlertX - Network scanner & notification framework
|
||||
|
||||
| [📑 Docker guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://jokob-sk.github.io/NetAlertX/) | [🔌 Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
|
||||
| [📑 Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) | [🚀 Releases](https://github.com/jokob-sk/NetAlertX/releases) | [📚 Docs](https://docs.netalertx.com/) | [🔌 Plugins](https://docs.netalertx.com/PLUGINS) | [🤖 Ask AI](https://gurubase.io/g/netalertx)
|
||||
|----------------------| ----------------------| ----------------------| ----------------------| ----------------------|
|
||||
|
||||
<a href="https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/docs/img/GENERAL/github_social_image.jpg" target="_blank">
|
||||
@@ -16,12 +16,12 @@
|
||||
Head to [https://netalertx.com/](https://netalertx.com/) for more gifs and screenshots 📷.
|
||||
|
||||
> [!NOTE]
|
||||
> There is also an experimental 🧪 [bare-metal install](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) method available.
|
||||
> There is also an experimental 🧪 [bare-metal install](https://docs.netalertx.com/HW_INSTALL) method available.
|
||||
|
||||
## 📕 Basic Usage
|
||||
|
||||
> [!WARNING]
|
||||
> You will have to run the container on the `host` network and specify `SCAN_SUBNETS` unless you use other [plugin scanners](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). The initial scan can take a few minutes, so please wait 5-10 minutes for the initial discovery to finish.
|
||||
> You will have to run the container on the `host` network and specify `SCAN_SUBNETS` unless you use other [plugin scanners](https://docs.netalertx.com/PLUGINS). The initial scan can take a few minutes, so please wait 5-10 minutes for the initial discovery to finish.
|
||||
|
||||
```bash
|
||||
docker run -d --rm --network=host \
|
||||
@@ -35,7 +35,7 @@ docker run -d --rm --network=host \
|
||||
|
||||
> Runtime UID/GID: The image defaults to a service user `netalertx` (UID/GID 20211). A separate readonly lock owner also uses UID/GID 20211 for 004/005 immutability. You can override the runtime UID/GID at build (ARG) or run (`--user` / compose `user:`) but must align writable mounts (`/data`, `/tmp*`) and tmpfs `uid/gid` to that choice.
|
||||
|
||||
See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md).
|
||||
See alternative [docked-compose examples](https://docs.netalertx.com/DOCKER_COMPOSE).
|
||||
|
||||
### Default ports
|
||||
|
||||
@@ -48,11 +48,11 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
|
||||
|
||||
| Variable | Description | Example/Default Value |
|
||||
| :------------- |:------------------------| -----:|
|
||||
| `PUID` |Runtime UID override | `20211` |
|
||||
| `PUID` |Runtime UID override, set to `0` to run as root. | `20211` |
|
||||
| `PGID` |Runtime GID override | `20211` |
|
||||
| `PORT` |Port of the web interface | `20211` |
|
||||
| `LISTEN_ADDR` |Set the specific IP Address for the listener address for the nginx webserver (web interface). This could be useful when using multiple subnets to hide the web interface from all untrusted networks. | `0.0.0.0` |
|
||||
|`LOADED_PLUGINS` | Default [plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md) to load. Plugins cannot be loaded with `APP_CONF_OVERRIDE`, you need to use this variable instead and then specify the plugins settings with `APP_CONF_OVERRIDE`. | `["PIHOLE","ASUSWRT"]` |
|
||||
|`LOADED_PLUGINS` | Default [plugins](https://docs.netalertx.com/PLUGINS) to load. Plugins cannot be loaded with `APP_CONF_OVERRIDE`, you need to use this variable instead and then specify the plugins settings with `APP_CONF_OVERRIDE`. | `["PIHOLE","ASUSWRT"]` |
|
||||
|`APP_CONF_OVERRIDE` | JSON override for settings (except `LOADED_PLUGINS`). | `{"SCAN_SUBNETS":"['192.168.1.0/24 --interface=eth1']","GRAPHQL_PORT":"20212"}` |
|
||||
|`ALWAYS_FRESH_INSTALL` | ⚠ If `true` will delete the content of the `/db` & `/config` folders. For testing purposes. Can be coupled with [watchtower](https://github.com/containrrr/watchtower) to have an always freshly installed `netalertx`/`netalertx-dev` image. | `true` |
|
||||
|
||||
@@ -61,16 +61,16 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
|
||||
### Docker paths
|
||||
|
||||
> [!NOTE]
|
||||
> See also [Backup strategies](https://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md).
|
||||
> See also [Backup strategies](https://docs.netalertx.com/BACKUPS).
|
||||
|
||||
| Required | Path | Description |
|
||||
| :------------- | :------------- | :-------------|
|
||||
| ✅ | `:/data` | Folder which needs to contain a `/db` and `/config` sub-folders. |
|
||||
| ✅ | `/etc/localtime:/etc/localtime:ro` | Ensuring the timezone is the same as on the server. |
|
||||
| | `:/tmp/log` | Logs folder useful for debugging if you have issues setting up the container |
|
||||
| | `:/tmp/api` | The [API endpoint](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) containing static (but regularly updated) json and other files. Path configurable via `NETALERTX_API` environment variable. |
|
||||
| | `:/app/front/plugins/<plugin>/ignore_plugin` | Map a file `ignore_plugin` to ignore a plugin. Plugins can be soft-disabled via settings. More in the [Plugin docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md). |
|
||||
| | `:/etc/resolv.conf` | Use a custom `resolv.conf` file for [better name resolution](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REVERSE_DNS.md). |
|
||||
| | `:/tmp/api` | The [API endpoint](https://docs.netalertx.com/API) containing static (but regularly updated) json and other files. Path configurable via `NETALERTX_API` environment variable. |
|
||||
| | `:/app/front/plugins/<plugin>/ignore_plugin` | Map a file `ignore_plugin` to ignore a plugin. Plugins can be soft-disabled via settings. More in the [Plugin docs](https://docs.netalertx.com/PLUGINS). |
|
||||
| | `:/etc/resolv.conf` | Use a custom `resolv.conf` file for [better name resolution](https://docs.netalertx.com/REVERSE_DNS). |
|
||||
|
||||
### Folder structure
|
||||
|
||||
@@ -100,23 +100,23 @@ sudo chmod -R a+rwx /local_data_dir
|
||||
|
||||
#### Setting up scanners
|
||||
|
||||
You have to specify which network(s) should be scanned. This is done by entering subnets that are accessible from the host. If you use the default `ARPSCAN` plugin, you have to specify at least one valid subnet and interface in the `SCAN_SUBNETS` setting. See the documentation on [How to set up multiple SUBNETS, VLANs and what are limitations](https://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) for troubleshooting and more advanced scenarios.
|
||||
You have to specify which network(s) should be scanned. This is done by entering subnets that are accessible from the host. If you use the default `ARPSCAN` plugin, you have to specify at least one valid subnet and interface in the `SCAN_SUBNETS` setting. See the documentation on [How to set up multiple SUBNETS, VLANs and what are limitations](https://docs.netalertx.com/SUBNETS) for troubleshooting and more advanced scenarios.
|
||||
|
||||
If you are running PiHole you can synchronize devices directly. Check the [PiHole configuration guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PIHOLE_GUIDE.md) for details.
|
||||
If you are running PiHole you can synchronize devices directly. Check the [PiHole configuration guide](https://docs.netalertx.com/PIHOLE_GUIDE) for details.
|
||||
|
||||
> [!NOTE]
|
||||
> You can bulk-import devices via the [CSV import method](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md).
|
||||
> You can bulk-import devices via the [CSV import method](https://docs.netalertx.com/DEVICES_BULK_EDITING).
|
||||
|
||||
#### Community guides
|
||||
|
||||
You can read or watch several [community configuration guides](https://github.com/jokob-sk/NetAlertX/blob/main/docs/COMMUNITY_GUIDES.md) in Chinese, Korean, German, or French.
|
||||
You can read or watch several [community configuration guides](https://docs.netalertx.com/COMMUNITY_GUIDES) in Chinese, Korean, German, or French.
|
||||
|
||||
> Please note these might be outdated. Rely on official documentation first.
|
||||
|
||||
#### Common issues
|
||||
|
||||
- Before creating a new issue, please check if a similar issue was [already resolved](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed).
|
||||
- Check also common issues and [debugging tips](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEBUG_TIPS.md).
|
||||
- Check also common issues and [debugging tips](https://docs.netalertx.com/DEBUG_TIPS).
|
||||
|
||||
## 💙 Support me
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# The NetAlertX Container Operator's Guide
|
||||
|
||||
> [!WARNING]
|
||||
> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://jokob-sk.github.io/NetAlertX/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
|
||||
> ⚠️ **Important:** The docker-compose has recently changed. Carefully read the [Migration guide](https://docs.netalertx.com/MIGRATION/?h=migrat#12-migration-from-netalertx-v25524) for detailed instructions.
|
||||
|
||||
This guide assumes you are starting with the official `docker-compose.yml` file provided with the project. We strongly recommend you start with or migrate to this file as your baseline and modify it to suit your specific needs (e.g., changing file paths). While there are many ways to configure NetAlertX, the default file is designed to meet the mandatory security baseline with layer-2 networking capabilities while operating securely and without startup warnings.
|
||||
|
||||
|
||||
@@ -1,5 +1,9 @@
|
||||
# Docker Swarm Deployment Guide (IPvlan)
|
||||
|
||||
> [!NOTE]
|
||||
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
|
||||
|
||||
|
||||
This guide describes how to deploy **NetAlertX** in a **Docker Swarm** environment using an `ipvlan` network. This enables the container to receive a LAN IP address directly, which is ideal for network monitoring.
|
||||
|
||||
---
|
||||
@@ -68,4 +72,3 @@ networks:
|
||||
* Make sure the assigned IP (`192.168.1.240` above) is not in use or managed by DHCP.
|
||||
* You may also use a node label constraint instead of `node.role == manager` for more control.
|
||||
|
||||
|
||||
|
||||
@@ -38,16 +38,28 @@ NetAlertX requires certain paths to be writable at runtime. These paths should b
|
||||
|
||||
> All these paths will have **UID 20211 / GID 20211** inside the container. Files on the host will appear owned by `20211:20211`.
|
||||
|
||||
You can cahnge the default PUID and GUID with env variables:
|
||||
## Running as `root`
|
||||
|
||||
You can override the default PUID and PGID using environment variables:
|
||||
|
||||
```yaml
|
||||
...
|
||||
environment:
|
||||
PUID: 20211 # Runtime PUID override
|
||||
PUID: 20211 # Runtime PUID override, set to 0 to run as root
|
||||
PGID: 20211 # Runtime PGID override
|
||||
...
|
||||
```
|
||||
|
||||
To run as the root user, it usually looks like this (verify the IDs on your server first by executing `id root`):
|
||||
|
||||
```yaml
|
||||
...
|
||||
environment:
|
||||
PUID: 0 # Runtime PUID override, set to 0 to run as root
|
||||
PGID: 100 # Runtime PGID override
|
||||
...
|
||||
```
|
||||
|
||||
### Solution
|
||||
|
||||
1. **Run the container once as root** (`--user "0"`) to allow it to correct permissions automatically:
|
||||
|
||||
@@ -2,24 +2,24 @@
|
||||
|
||||
## Installation options
|
||||
|
||||
NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised Home Assistant instance, as an Unraid app, and lastly, on bare metal.
|
||||
NetAlertX can be installed several ways. The best supported option is Docker, followed by a supervised Home Assistant instance, as an Unraid app, and lastly, on bare metal.
|
||||
|
||||
- [[Installation] Docker (recommended)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md)
|
||||
- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
|
||||
- [[Installation] Unraid App](https://unraid.net/community/apps)
|
||||
- [[Installation] Bare metal (experimental - looking for maintainers)](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md)
|
||||
- [[Installation] Docker (recommended)](https://docs.netalertx.com/DOCKER_INSTALLATION)
|
||||
- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
|
||||
- [[Installation] Unraid App](https://unraid.net/community/apps)
|
||||
- [[Installation] Bare metal (experimental - looking for maintainers)](https://docs.netalertx.com/HW_INSTALL)
|
||||
|
||||
|
||||
## Help
|
||||
|
||||
If facing issues, please spend a few minutes seraching.
|
||||
If facing issues, please spend a few minutes seraching.
|
||||
|
||||
- Check [common issues](./COMMON_ISSUES.md)
|
||||
- Have a look at [Community guides](./COMMUNITY_GUIDES.md)
|
||||
- [Search closed or open issues or discussions](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue)
|
||||
- Have a look at [Community guides](./COMMUNITY_GUIDES.md)
|
||||
- [Search closed or open issues or discussions](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue)
|
||||
- Check [Discord](https://discord.gg/NczTUTWyRr)
|
||||
|
||||
> [!NOTE]
|
||||
> If you can't find a solution anywhere, ask in Discord if you think it's a quick question, otherwise open a new [issue](https://github.com/jokob-sk/NetAlertX/issues/new?template=setup-help.yml). Please fill in as much as possible to speed up the help process.
|
||||
> If you can't find a solution anywhere, ask in Discord if you think it's a quick question, otherwise open a new [issue](https://github.com/jokob-sk/NetAlertX/issues/new?template=setup-help.yml). Please fill in as much as possible to speed up the help process.
|
||||
>
|
||||
|
||||
|
||||
@@ -297,5 +297,5 @@ sudo chmod -R a+rwx /local_data_dir
|
||||
```
|
||||
|
||||
8. Start the container and verify everything works as expeexpected.
|
||||
9. Check the [Permissions -> Writable-paths](https://jokob-sk.github.io/NetAlertX/FILE_PERMISSIONS/#writable-paths) what directories to mount if you'd like to access the API or log files.
|
||||
|
||||
9. Check the [Permissions -> Writable-paths](https://docs.netalertx.com/FILE_PERMISSIONS/#writable-paths) what directories to mount if you'd like to access the API or log files.
|
||||
|
||||
|
||||
1041
docs/PLUGINS_DEV.md
1041
docs/PLUGINS_DEV.md
File diff suppressed because it is too large
Load Diff
378
docs/PLUGINS_DEV_DATASOURCES.md
Normal file
378
docs/PLUGINS_DEV_DATASOURCES.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# Plugin Data Sources
|
||||
|
||||
Learn how to configure different data sources for your plugin.
|
||||
|
||||
## Overview
|
||||
|
||||
Data sources determine **where the plugin gets its data** and **what format it returns**. NetAlertX supports multiple data source types, each suited for different use cases.
|
||||
|
||||
| Data Source | Type | Purpose | Returns | Example |
|
||||
|-------------|------|---------|---------|---------|
|
||||
| `script` | Code Execution | Execute Linux commands or Python scripts | Pipeline | Scan network, collect metrics, call APIs |
|
||||
| `app-db-query` | Database Query | Query the NetAlertX database | Result set | Show devices, open ports, recent events |
|
||||
| `sqlite-db-query` | External DB | Query external SQLite databases | Result set | PiHole database, external logs |
|
||||
| `template` | Template | Generate values from templates | Values | Initialize default settings |
|
||||
|
||||
## Data Source: `script`
|
||||
|
||||
Execute any Linux command or Python script and capture its output.
|
||||
|
||||
### Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"data_source": "script",
|
||||
"show_ui": true,
|
||||
"mapped_to_table": "CurrentScan"
|
||||
}
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
1. Command specified in `CMD` setting is executed
|
||||
2. Script writes results to `/tmp/log/plugins/last_result.<PREFIX>.log`
|
||||
3. Core reads file and parses pipe-delimited results
|
||||
4. Results inserted into database
|
||||
|
||||
### Example: Simple Python Script
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "CMD",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "python3 /app/front/plugins/my_plugin/script.py",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Command"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Bash Script
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "CMD",
|
||||
"default_value": "bash /app/front/plugins/my_plugin/script.sh",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Command"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
- **Always use absolute paths** (e.g., `/app/front/plugins/...`)
|
||||
- **Use `plugin_helper.py`** for output formatting
|
||||
- **Add timeouts** via `RUN_TIMEOUT` setting (default: 60s)
|
||||
- **Log errors** to `/tmp/log/plugins/<PREFIX>.log`
|
||||
- **Handle missing dependencies gracefully**
|
||||
|
||||
### Output Format
|
||||
|
||||
Must write to: `/tmp/log/plugins/last_result.<PREFIX>.log`
|
||||
|
||||
Format: Pipe-delimited, 9 or 13 columns
|
||||
|
||||
See [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) for exact format
|
||||
|
||||
---
|
||||
|
||||
## Data Source: `app-db-query`
|
||||
|
||||
Query the NetAlertX SQLite database and display results.
|
||||
|
||||
### Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"data_source": "app-db-query",
|
||||
"show_ui": true,
|
||||
"mapped_to_table": "CurrentScan"
|
||||
}
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
1. SQL query specified in `CMD` setting is executed against `app.db`
|
||||
2. Results parsed according to column definitions
|
||||
3. Inserted into plugin display/database
|
||||
|
||||
### SQL Query Requirements
|
||||
|
||||
- Must return exactly **9 or 13 columns** matching the [data contract](PLUGINS_DEV_DATA_CONTRACT.md)
|
||||
- Column names must match (order matters!)
|
||||
- Must be **readable SQLite SQL** (not vendor-specific)
|
||||
|
||||
### Example: Open Ports from Nmap
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "CMD",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "SELECT dv.devName as Object_PrimaryID, cast(dv.devLastIP as VARCHAR(100)) || ':' || cast(SUBSTR(ns.Port, 0, INSTR(ns.Port, '/')) as VARCHAR(100)) as Object_SecondaryID, datetime() as DateTime, ns.Service as Watched_Value1, ns.State as Watched_Value2, null as Watched_Value3, null as Watched_Value4, ns.Extra as Extra, dv.devMac as ForeignKey FROM (SELECT * FROM Nmap_Scan) ns LEFT JOIN (SELECT devName, devMac, devLastIP FROM Devices) dv ON ns.MAC = dv.devMac",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "SQL to run"}],
|
||||
"description": [{"language_code": "en_us", "string": "This SQL query populates the plugin table"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Recent Device Events
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
e.EventValue as Object_PrimaryID,
|
||||
d.devName as Object_SecondaryID,
|
||||
e.EventDateTime as DateTime,
|
||||
e.EventType as Watched_Value1,
|
||||
d.devLastIP as Watched_Value2,
|
||||
null as Watched_Value3,
|
||||
null as Watched_Value4,
|
||||
e.EventDetails as Extra,
|
||||
d.devMac as ForeignKey
|
||||
FROM
|
||||
Events e
|
||||
LEFT JOIN
|
||||
Devices d ON e.DeviceMac = d.devMac
|
||||
WHERE
|
||||
e.EventDateTime > datetime('now', '-24 hours')
|
||||
ORDER BY
|
||||
e.EventDateTime DESC
|
||||
```
|
||||
|
||||
See the [Database documentation](./DATABASE.md) for a list of common columns.
|
||||
|
||||
---
|
||||
|
||||
## Data Source: `sqlite-db-query`
|
||||
|
||||
Query an **external SQLite database** mounted in the container.
|
||||
|
||||
### Configuration
|
||||
|
||||
First, define the database path in a setting:
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "DB_PATH",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "/etc/pihole/pihole-FTL.db",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Database path"}],
|
||||
"description": [{"language_code": "en_us", "string": "Path to external SQLite database"}]
|
||||
}
|
||||
```
|
||||
|
||||
Then set data source and query:
|
||||
|
||||
```json
|
||||
{
|
||||
"data_source": "sqlite-db-query",
|
||||
"show_ui": true
|
||||
}
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
1. External database file path specified in `DB_PATH` setting
|
||||
2. Database mounted at that path (e.g., via Docker volume)
|
||||
3. SQL query executed against external database using `EXTERNAL_<PREFIX>.` prefix
|
||||
4. Results returned in standard format
|
||||
|
||||
### SQL Query Example: PiHole Data
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "CMD",
|
||||
"default_value": "SELECT hwaddr as Object_PrimaryID, cast('http://' || (SELECT ip FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as VARCHAR(100)) || ':' || cast(SUBSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), 0, INSTR((SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1), '/')) as VARCHAR(100)) as Object_SecondaryID, datetime() as DateTime, macVendor as Watched_Value1, lastQuery as Watched_Value2, (SELECT name FROM EXTERNAL_PIHOLE.network_addresses WHERE network_id = id ORDER BY lastseen DESC LIMIT 1) as Watched_Value3, null as Watched_Value4, '' as Extra, hwaddr as ForeignKey FROM EXTERNAL_PIHOLE.network WHERE hwaddr NOT LIKE 'ip-%' AND hwaddr <> '00:00:00:00:00:00'",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "SQL to run"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Key Points
|
||||
|
||||
- **Prefix all external tables** with `EXTERNAL_<PREFIX>.`
|
||||
- For PiHole (`PIHOLE` prefix): `EXTERNAL_PIHOLE.network`
|
||||
- For custom database (`CUSTOM` prefix): `EXTERNAL_CUSTOM.my_table`
|
||||
- **Database must be valid SQLite**
|
||||
- **Path must be accessible** inside the container
|
||||
- **No columns beyond the data contract** required
|
||||
|
||||
### Docker Volume Setup
|
||||
|
||||
To mount external database in docker-compose:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
netalertx:
|
||||
volumes:
|
||||
- /path/on/host/pihole-FTL.db:/etc/pihole/pihole-FTL.db:ro
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Source: `template`
|
||||
|
||||
Generate values from a template. Usually used for initialization and default settings.
|
||||
|
||||
### Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"data_source": "template"
|
||||
}
|
||||
```
|
||||
|
||||
### How It Works
|
||||
|
||||
- **Not widely used** in standard plugins
|
||||
- Used internally for generating default values
|
||||
- Check `newdev_template` plugin for implementation example
|
||||
|
||||
### Example: Default Device Template
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "DEFAULT_DEVICE_PROPERTIES",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "textarea", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "type=Unknown|vendor=Unknown",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Default properties"}]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Source: `plugin_type`
|
||||
|
||||
Declare the plugin category. Controls where settings appear in the UI.
|
||||
|
||||
### Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"data_source": "plugin_type",
|
||||
"value": "scanner"
|
||||
}
|
||||
```
|
||||
|
||||
### Supported Values
|
||||
|
||||
| Value | Section | Purpose |
|
||||
|-------|---------|---------|
|
||||
| `scanner` | Device Scanners | Discovers devices on network |
|
||||
| `system` | System Plugins | Core system functionality |
|
||||
| `publisher` | Notification/Alert Plugins | Sends notifications/alerts |
|
||||
| `importer` | Data Importers | Imports devices from external sources |
|
||||
| `other` | Other Plugins | Miscellaneous functionality |
|
||||
|
||||
### Example
|
||||
|
||||
```json
|
||||
{
|
||||
"settings": [
|
||||
{
|
||||
"function": "plugin_type",
|
||||
"type": {"dataType": "string", "elements": []},
|
||||
"default_value": "scanner",
|
||||
"options": ["scanner"],
|
||||
"data_source": "plugin_type",
|
||||
"value": "scanner",
|
||||
"localized": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Execution Order
|
||||
|
||||
Control plugin execution priority. Higher priority plugins run first.
|
||||
|
||||
```json
|
||||
{
|
||||
"execution_order": "Layer_0"
|
||||
}
|
||||
```
|
||||
|
||||
### Levels (highest to lowest priority)
|
||||
|
||||
- `Layer_0` - Highest priority (run first)
|
||||
- `Layer_1`
|
||||
- `Layer_2`
|
||||
- ...
|
||||
|
||||
### Example: Device Discovery
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"code_name": "device_scanner",
|
||||
"unique_prefix": "DEVSCAN",
|
||||
"execution_order": "Layer_0",
|
||||
"data_source": "script",
|
||||
"mapped_to_table": "CurrentScan"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Script Source
|
||||
- **Pros:** Flexible, can call external tools
|
||||
- **Cons:** Slower than database queries
|
||||
- **Optimization:** Add caching, use timeouts
|
||||
- **Default timeout:** 60 seconds (set `RUN_TIMEOUT`)
|
||||
|
||||
### Database Query Source
|
||||
- **Pros:** Fast, native query optimization
|
||||
- **Cons:** Limited to SQL capabilities
|
||||
- **Optimization:** Use indexes, avoid complex joins
|
||||
- **Timeout:** Usually instant
|
||||
|
||||
### External DB Query Source
|
||||
- **Pros:** Direct access to external data
|
||||
- **Cons:** Network latency, external availability
|
||||
- **Optimization:** Use indexes in external DB, selective queries
|
||||
- **Timeout:** Depends on DB response time
|
||||
|
||||
---
|
||||
|
||||
## Debugging Data Sources
|
||||
|
||||
### Check Script Output
|
||||
|
||||
```bash
|
||||
# Run script manually
|
||||
python3 /app/front/plugins/my_plugin/script.py
|
||||
|
||||
# Check result file
|
||||
cat /tmp/log/plugins/last_result.MYPREFIX.log
|
||||
```
|
||||
|
||||
### Test SQL Query
|
||||
|
||||
```bash
|
||||
# Connect to app database
|
||||
sqlite3 /data/db/app.db
|
||||
|
||||
# Run query
|
||||
sqlite> SELECT ... ;
|
||||
```
|
||||
|
||||
### Monitor Execution
|
||||
|
||||
```bash
|
||||
# Watch backend logs
|
||||
tail -f /tmp/log/stdout.log | grep -i "data_source\|MYPREFIX"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) - Output format specification
|
||||
- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md) - How to define settings
|
||||
- [Quick Start Guide](PLUGINS_DEV_QUICK_START.md) - Create your first plugin
|
||||
- [Database Schema](DATABASE.md) - Available tables and columns
|
||||
- [Debugging Plugins](DEBUG_PLUGINS.md) - Troubleshooting data issues
|
||||
253
docs/PLUGINS_DEV_DATA_CONTRACT.md
Normal file
253
docs/PLUGINS_DEV_DATA_CONTRACT.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Plugin Data Contract
|
||||
|
||||
This document specifies the exact interface between plugins and the NetAlertX core.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Every plugin must output data in this exact format to be recognized and processed correctly.
|
||||
|
||||
## Overview
|
||||
|
||||
Plugins communicate with NetAlertX by writing results to a **pipe-delimited log file**. The core reads this file, parses the data, and processes it for notifications, device discovery, and data integration.
|
||||
|
||||
**File Location:** `/tmp/log/plugins/last_result.<PREFIX>.log`
|
||||
|
||||
**Format:** Pipe-delimited (`|`), one record per line
|
||||
|
||||
**Required Columns:** 9 (mandatory) + up to 4 optional helper columns = 13 total
|
||||
|
||||
## Column Specification
|
||||
|
||||
> [!NOTE]
|
||||
> The order of columns is **FIXED** and cannot be changed. All 9 mandatory columns must be provided. If you use any optional column (`HelpVal1`), you must supply all optional columns (`HelpVal1` through `HelpVal4`).
|
||||
|
||||
### Mandatory Columns (0–8)
|
||||
|
||||
| Order | Column Name | Type | Required | Description |
|
||||
|-------|-------------|------|----------|-------------|
|
||||
| 0 | `Object_PrimaryID` | string | **YES** | The primary identifier for grouping. Examples: device MAC, hostname, service name, or any unique ID |
|
||||
| 1 | `Object_SecondaryID` | string | no | Secondary identifier for relationships (e.g., IP address, port, sub-ID). Use `null` if not needed |
|
||||
| 2 | `DateTime` | string | **YES** | Timestamp when the event/data was collected. Format: `YYYY-MM-DD HH:MM:SS` |
|
||||
| 3 | `Watched_Value1` | string | **YES** | Primary watched value. Changes trigger notifications. Examples: IP address, status, version |
|
||||
| 4 | `Watched_Value2` | string | no | Secondary watched value. Use `null` if not needed |
|
||||
| 5 | `Watched_Value3` | string | no | Tertiary watched value. Use `null` if not needed |
|
||||
| 6 | `Watched_Value4` | string | no | Quaternary watched value. Use `null` if not needed |
|
||||
| 7 | `Extra` | string | no | Any additional metadata to display in UI and notifications. Use `null` if not needed |
|
||||
| 8 | `ForeignKey` | string | no | Foreign key linking to parent object (usually MAC address for device relationship). Use `null` if not needed |
|
||||
|
||||
### Optional Columns (9–12)
|
||||
|
||||
| Order | Column Name | Type | Required | Description |
|
||||
|-------|-------------|------|----------|-------------|
|
||||
| 9 | `HelpVal1` | string | *conditional* | Helper value 1. If used, all help values must be supplied |
|
||||
| 10 | `HelpVal2` | string | *conditional* | Helper value 2. If used, all help values must be supplied |
|
||||
| 11 | `HelpVal3` | string | *conditional* | Helper value 3. If used, all help values must be supplied |
|
||||
| 12 | `HelpVal4` | string | *conditional* | Helper value 4. If used, all help values must be supplied |
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Empty/Null Values
|
||||
|
||||
- Represent empty values as the literal string `null` (not Python `None`, SQL `NULL`, or empty string)
|
||||
- Example: `device_id|null|2023-01-02 15:56:30|status|null|null|null|null|null`
|
||||
|
||||
### Watched Values
|
||||
|
||||
**What are Watched Values?**
|
||||
|
||||
Watched values are fields that the NetAlertX core monitors for **changes between scans**. When a watched value differs from the previous scan, it can trigger notifications.
|
||||
|
||||
**How to use them:**
|
||||
|
||||
- `Watched_Value1`: Always required; primary indicator of status/state
|
||||
- `Watched_Value2–4`: Optional; use for secondary/tertiary state information
|
||||
- Leave unused ones as `null`
|
||||
|
||||
**Example:**
|
||||
|
||||
- Device scanner: `Watched_Value1 = "online"` or `"offline"`
|
||||
- Port scanner: `Watched_Value1 = "80"` (port number), `Watched_Value2 = "open"` (state)
|
||||
- Service monitor: `Watched_Value1 = "200"` (HTTP status), `Watched_Value2 = "0.45"` (response time)
|
||||
|
||||
### Foreign Key
|
||||
|
||||
Use the `ForeignKey` column to link objects to a parent device by MAC address:
|
||||
|
||||
```
|
||||
device_name|192.168.1.100|2023-01-02 15:56:30|online|null|null|null|Found on network|aa:bb:cc:dd:ee:ff
|
||||
↑
|
||||
ForeignKey (MAC)
|
||||
```
|
||||
|
||||
This allows NetAlertX to:
|
||||
|
||||
- Display the object on the device details page
|
||||
- Send notifications when the parent device is involved
|
||||
- Link events across plugins
|
||||
|
||||
## Examples
|
||||
|
||||
### Valid Data (9 columns, minimal)
|
||||
|
||||
```csv
|
||||
https://example.com|null|2023-01-02 15:56:30|200|null|null|null|null|null
|
||||
printer-hp-1|192.168.1.50|2023-01-02 15:56:30|online|50%|null|null|Last seen in office|aa:11:22:33:44:55
|
||||
gateway.local|null|2023-01-02 15:56:30|active|v2.1.5|null|null|Firmware version|null
|
||||
```
|
||||
|
||||
### Valid Data (13 columns, with helpers)
|
||||
|
||||
```csv
|
||||
service-api|192.168.1.100:8080|2023-01-02 15:56:30|200|45ms|true|null|Responding normally|aa:bb:cc:dd:ee:ff|extra1|extra2|extra3|extra4
|
||||
host-web-1|10.0.0.20|2023-01-02 15:56:30|active|256GB|online|ok|Production server|null|cpu:80|mem:92|disk:45|alerts:0
|
||||
```
|
||||
|
||||
### Invalid Data (Common Errors)
|
||||
|
||||
❌ **Missing required column** (only 8 separators instead of 8):
|
||||
```csv
|
||||
https://google.com|null|2023-01-02 15:56:30|200|0.7898||null|null
|
||||
↑
|
||||
Missing pipe
|
||||
```
|
||||
|
||||
❌ **Missing mandatory Watched_Value1** (column 3):
|
||||
```csv
|
||||
https://duckduckgo.com|192.168.1.1|2023-01-02 15:56:30|null|0.9898|null|null|Best|null
|
||||
↑
|
||||
Must not be null
|
||||
```
|
||||
|
||||
❌ **Incomplete optional columns** (has HelpVal1 but missing HelpVal2–4):
|
||||
```csv
|
||||
device|null|2023-01-02 15:56:30|status|null|null|null|null|null|helper1
|
||||
↑
|
||||
Has helper but incomplete
|
||||
```
|
||||
|
||||
✅ **Complete with helpers** (all 4 helpers provided):
|
||||
```csv
|
||||
device|null|2023-01-02 15:56:30|status|null|null|null|null|null|h1|h2|h3|h4
|
||||
```
|
||||
|
||||
✅ **Complete without helpers** (9 columns exactly):
|
||||
```csv
|
||||
device|null|2023-01-02 15:56:30|status|null|null|null|null|null
|
||||
```
|
||||
|
||||
## Using `plugin_helper.py`
|
||||
|
||||
The easiest way to ensure correct output is to use the [`plugin_helper.py`](../front/plugins/plugin_helper.py) library:
|
||||
|
||||
```python
|
||||
from plugin_helper import Plugin_Objects
|
||||
|
||||
# Initialize with your plugin's prefix
|
||||
plugin_objects = Plugin_Objects("YOURPREFIX")
|
||||
|
||||
# Add objects
|
||||
plugin_objects.add_object(
|
||||
Object_PrimaryID="device_id",
|
||||
Object_SecondaryID="192.168.1.1",
|
||||
DateTime="2023-01-02 15:56:30",
|
||||
Watched_Value1="online",
|
||||
Watched_Value2=None,
|
||||
Watched_Value3=None,
|
||||
Watched_Value4=None,
|
||||
Extra="Additional data",
|
||||
ForeignKey="aa:bb:cc:dd:ee:ff",
|
||||
HelpVal1=None,
|
||||
HelpVal2=None,
|
||||
HelpVal3=None,
|
||||
HelpVal4=None
|
||||
)
|
||||
|
||||
# Write results (handles formatting, sanitization, and file creation)
|
||||
plugin_objects.write_result_file()
|
||||
```
|
||||
|
||||
The library automatically:
|
||||
|
||||
- Validates data types
|
||||
- Sanitizes string values
|
||||
- Normalizes MAC addresses
|
||||
- Writes to the correct file location
|
||||
- Creates the file in `/tmp/log/plugins/last_result.<PREFIX>.log`
|
||||
|
||||
## De-duplication
|
||||
|
||||
The core runs **de-duplication once per hour** on the `Plugins_Objects` table:
|
||||
|
||||
- **Duplicate Detection Key:** Combination of `Object_PrimaryID`, `Object_SecondaryID`, `Plugin` (auto-filled from `unique_prefix`), and `UserData`
|
||||
- **Resolution:** Oldest duplicate entries are removed, newest are kept
|
||||
- **Use Case:** Prevents duplicate notifications when the same object is detected multiple times
|
||||
|
||||
## DateTime Format
|
||||
|
||||
**Required Format:** `YYYY-MM-DD HH:MM:SS`
|
||||
|
||||
**Examples:**
|
||||
- `2023-01-02 15:56:30` ✅
|
||||
- `2023-1-2 15:56:30` ❌ (missing leading zeros)
|
||||
- `2023-01-02T15:56:30` ❌ (wrong separator)
|
||||
- `15:56:30 2023-01-02` ❌ (wrong order)
|
||||
|
||||
**Python Helper:**
|
||||
```python
|
||||
from datetime import datetime
|
||||
|
||||
# Current time in correct format
|
||||
now = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
|
||||
# Output: "2023-01-02 15:56:30"
|
||||
```
|
||||
|
||||
**Bash Helper:**
|
||||
```bash
|
||||
# Current time in correct format
|
||||
date '+%Y-%m-%d %H:%M:%S'
|
||||
# Output: 2023-01-02 15:56:30
|
||||
```
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before writing your plugin's `script.py`, ensure:
|
||||
|
||||
- [ ] **9 or 13 columns** in each output line (8 or 12 pipe separators)
|
||||
- [ ] **Mandatory columns filled:**
|
||||
- Column 0: `Object_PrimaryID` (not null)
|
||||
- Column 2: `DateTime` in `YYYY-MM-DD HH:MM:SS` format
|
||||
- Column 3: `Watched_Value1` (not null)
|
||||
- [ ] **Null values as literal string** `null` (not empty string or special chars)
|
||||
- [ ] **No extra pipes or misaligned columns**
|
||||
- [ ] **If using optional helpers** (columns 9–12), all 4 must be present
|
||||
- [ ] **File written to** `/tmp/log/plugins/last_result.<PREFIX>.log`
|
||||
- [ ] **One record per line** (newline-delimited)
|
||||
- [ ] **No header row** (data only)
|
||||
|
||||
## Debugging
|
||||
|
||||
**View raw plugin output:**
|
||||
```bash
|
||||
cat /tmp/log/plugins/last_result.YOURPREFIX.log
|
||||
```
|
||||
|
||||
**Check line count:**
|
||||
```bash
|
||||
wc -l /tmp/log/plugins/last_result.YOURPREFIX.log
|
||||
```
|
||||
|
||||
**Validate column count (should be 8 or 12 pipes per line):**
|
||||
```bash
|
||||
cat /tmp/log/plugins/last_result.YOURPREFIX.log | awk -F'|' '{print NF}' | sort | uniq
|
||||
# Output: 9 (for minimal) or 13 (for with helpers)
|
||||
```
|
||||
|
||||
**Check core processing in logs:**
|
||||
```bash
|
||||
tail -f /tmp/log/stdout.log | grep -i "YOURPREFIX\|Plugins_Objects"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md) - How to accept user input
|
||||
- [Data Sources](PLUGINS_DEV_DATASOURCES.md) - Different data source types
|
||||
- [Debugging Plugins](DEBUG_PLUGINS.md) - Troubleshooting plugin issues
|
||||
175
docs/PLUGINS_DEV_QUICK_START.md
Normal file
175
docs/PLUGINS_DEV_QUICK_START.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# Plugin Development Quick Start
|
||||
|
||||
Get a working plugin up and running in 5 minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Read [Development Environment Setup Guide](./DEV_ENV_SETUP.md) to set up your local environment
|
||||
- Understand [Plugin Architecture Overview](PLUGINS_DEV.md)
|
||||
|
||||
## Quick Start Steps
|
||||
|
||||
### 1. Create Your Plugin Folder
|
||||
|
||||
Start from the template to get the basic structure:
|
||||
|
||||
```bash
|
||||
cd /workspaces/NetAlertX/front/plugins
|
||||
cp -r __template my_plugin
|
||||
cd my_plugin
|
||||
```
|
||||
|
||||
### 2. Update `config.json` Identifiers
|
||||
|
||||
Edit `my_plugin/config.json` and update these critical fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"code_name": "my_plugin",
|
||||
"unique_prefix": "MYPLN",
|
||||
"display_name": [{"language_code": "en_us", "string": "My Plugin"}],
|
||||
"description": [{"language_code": "en_us", "string": "My custom plugin"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Important:**
|
||||
- `code_name` must match the folder name
|
||||
- `unique_prefix` must be unique and uppercase (check existing plugins to avoid conflicts)
|
||||
- `unique_prefix` is used as a prefix for all generated settings (e.g., `MYPLN_RUN`, `MYPLN_CMD`)
|
||||
|
||||
### 3. Implement Your Script
|
||||
|
||||
Edit `my_plugin/script.py` and implement your data collection logic:
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
|
||||
import sys
|
||||
import os
|
||||
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../../server'))
|
||||
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '../plugins'))
|
||||
|
||||
from plugin_helper import Plugin_Objects, mylog
|
||||
from helper import get_setting_value
|
||||
from const import logPath
|
||||
|
||||
pluginName = "MYPLN"
|
||||
|
||||
LOG_PATH = logPath + "/plugins"
|
||||
LOG_FILE = os.path.join(LOG_PATH, f"script.{pluginName}.log")
|
||||
RESULT_FILE = os.path.join(LOG_PATH, f"last_result.{pluginName}.log")
|
||||
|
||||
# Initialize
|
||||
plugin_objects = Plugin_Objects(RESULT_FILE)
|
||||
|
||||
try:
|
||||
# Your data collection logic here
|
||||
# For example, scan something and collect results
|
||||
|
||||
# Add an object to results
|
||||
plugin_objects.add_object(
|
||||
Object_PrimaryID="example_id",
|
||||
Object_SecondaryID=None,
|
||||
DateTime="2023-01-02 15:56:30",
|
||||
Watched_Value1="value1",
|
||||
Watched_Value2=None,
|
||||
Watched_Value3=None,
|
||||
Watched_Value4=None,
|
||||
Extra="additional_data",
|
||||
ForeignKey=None
|
||||
)
|
||||
|
||||
# Write results to the log file
|
||||
plugin_objects.write_result_file()
|
||||
|
||||
except Exception as e:
|
||||
mylog("none", f"Error: {e}")
|
||||
sys.exit(1)
|
||||
```
|
||||
|
||||
### 4. Configure Execution
|
||||
|
||||
Edit the `RUN` and `CMD` settings in `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "RUN",
|
||||
"type": {"dataType":"string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "disabled",
|
||||
"options": ["disabled", "once", "schedule"],
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code":"en_us", "string": "When to run"}],
|
||||
"description": [{"language_code":"en_us", "string": "Enable plugin execution"}]
|
||||
},
|
||||
{
|
||||
"function": "CMD",
|
||||
"type": {"dataType":"string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "python3 /app/front/plugins/my_plugin/script.py",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code":"en_us", "string": "Command"}],
|
||||
"description": [{"language_code":"en_us", "string": "Command to execute"}]
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Test Your Plugin
|
||||
|
||||
#### In Dev Container
|
||||
|
||||
```bash
|
||||
# Test the script directly
|
||||
python3 /workspaces/NetAlertX/front/plugins/my_plugin/script.py
|
||||
|
||||
# Check the results
|
||||
cat /tmp/log/plugins/last_result.MYPLN.log
|
||||
```
|
||||
|
||||
#### Via UI
|
||||
|
||||
1. Restart backend: Run task `[Dev Container] Start Backend (Python)`
|
||||
2. Open Settings → Plugin Settings → My Plugin
|
||||
3. Set `My Plugin - When to run` to `once`
|
||||
4. Click Save
|
||||
5. Check `/tmp/log/plugins/last_result.MYPLN.log` for output
|
||||
|
||||
### 6. Check Results
|
||||
|
||||
Verify your plugin is working:
|
||||
|
||||
```bash
|
||||
# Check if result file was generated
|
||||
ls -la /tmp/log/plugins/last_result.MYPLN.log
|
||||
|
||||
# View contents
|
||||
cat /tmp/log/plugins/last_result.MYPLN.log
|
||||
|
||||
# Check backend logs for errors
|
||||
tail -f /tmp/log/stdout.log | grep "my_plugin\|MYPLN"
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you have a working basic plugin:
|
||||
|
||||
1. **Add Settings**: Customize behavior via user-configurable settings (see [PLUGINS_DEV_SETTINGS.md](PLUGINS_DEV_SETTINGS.md))
|
||||
2. **Implement Data Contract**: Structure your output correctly (see [PLUGINS_DEV_DATA_CONTRACT.md](PLUGINS_DEV_DATA_CONTRACT.md))
|
||||
3. **Configure UI**: Display plugin results in the web interface (see [PLUGINS_DEV_UI_COMPONENTS.md](PLUGINS_DEV_UI_COMPONENTS.md))
|
||||
4. **Map to Database**: Import data into NetAlertX tables like `CurrentScan` or `Devices`
|
||||
5. **Set Schedules**: Run your plugin on a schedule (see [PLUGINS_DEV_CONFIG.md](PLUGINS_DEV_CONFIG.md))
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| "Module not found" errors | Ensure `sys.path` includes `/app/server` and `/app/front/plugins` |
|
||||
| Settings not appearing | Restart backend and clear browser cache |
|
||||
| Results not showing up | Check `/tmp/log/plugins/*.log` and `/tmp/log/stdout.log` for errors |
|
||||
| Permission denied | Plugin runs in container, use absolute paths like `/app/front/plugins/...` |
|
||||
|
||||
## Resources
|
||||
|
||||
- [Full Plugin Development Guide](PLUGINS_DEV.md)
|
||||
- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md)
|
||||
- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md)
|
||||
- [Data Sources](PLUGINS_DEV_DATASOURCES.md)
|
||||
- [UI Components](PLUGINS_DEV_UI_COMPONENTS.md)
|
||||
- [Debugging Plugins](DEBUG_PLUGINS.md)
|
||||
518
docs/PLUGINS_DEV_SETTINGS.md
Normal file
518
docs/PLUGINS_DEV_SETTINGS.md
Normal file
@@ -0,0 +1,518 @@
|
||||
# Plugin Settings System
|
||||
|
||||
Learn how to let users configure your plugin via the NetAlertX UI Settings page.
|
||||
|
||||
> [!TIP]
|
||||
> For the higher-level settings flow and lifecycle, see [Settings System Documentation](./SETTINGS_SYSTEM.md).
|
||||
|
||||
## Overview
|
||||
|
||||
Plugin settings allow users to configure:
|
||||
|
||||
- **Execution schedule** (when the plugin runs)
|
||||
- **Runtime parameters** (API keys, URLs, thresholds)
|
||||
- **Behavior options** (which features to enable/disable)
|
||||
- **Command overrides** (customize the executed script)
|
||||
|
||||
All settings are defined in your plugin's `config.json` file under the `"settings"` array.
|
||||
|
||||
## Setting Definition Structure
|
||||
|
||||
Each setting is a JSON object with required and optional properties:
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "UNIQUE_CODE",
|
||||
"type": {
|
||||
"dataType": "string",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "input",
|
||||
"elementOptions": [],
|
||||
"transformers": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": "default_value_here",
|
||||
"options": [],
|
||||
"localized": ["name", "description"],
|
||||
"name": [
|
||||
{
|
||||
"language_code": "en_us",
|
||||
"string": "Display Name"
|
||||
}
|
||||
],
|
||||
"description": [
|
||||
{
|
||||
"language_code": "en_us",
|
||||
"string": "Help text describing the setting"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Required Properties
|
||||
|
||||
| Property | Type | Description | Example |
|
||||
|----------|------|-------------|---------|
|
||||
| `function` | string | Unique identifier for the setting. Used in manifest and when reading values. See [Reserved Function Names](#reserved-function-names) for special values | `"MY_CUSTOM_SETTING"` |
|
||||
| `type` | object | Defines the UI component and data type | See [Component Types](#component-types) |
|
||||
| `default_value` | varies | Initial value shown in UI | `"https://example.com"` |
|
||||
| `localized` | array | Which properties have translations | `["name", "description"]` |
|
||||
| `name` | array | Display name in Settings UI (localized) | See [Localized Strings](#localized-strings) |
|
||||
| `description` | array | Help text in Settings UI (localized) | See [Localized Strings](#localized-strings) |
|
||||
|
||||
## Optional Properties
|
||||
|
||||
| Property | Type | Description | Example |
|
||||
|----------|------|-------------|---------|
|
||||
| `options` | array | Valid values for select/checkbox controls | `["option1", "option2"]` |
|
||||
| `events` | string | Trigger action button: `"test"` or `"run"` | `"test"` for notifications |
|
||||
| `maxLength` | number | Character limit for input fields | `100` |
|
||||
| `readonly` | boolean | Make field read-only | `true` |
|
||||
| `override_value` | object | Template-based value override (WIP) | Work in Progress |
|
||||
|
||||
## Reserved Function Names
|
||||
|
||||
These function names have special meaning and control core plugin behavior:
|
||||
|
||||
### Core Execution Settings
|
||||
|
||||
| Function | Purpose | Type | Required | Options |
|
||||
|----------|---------|------|----------|---------|
|
||||
| `RUN` | **When to execute the plugin** | select | **YES** | `"disabled"`, `"once"`, `"schedule"`, `"always_after_scan"`, `"before_name_updates"`, `"on_new_device"`, `"before_config_save"` |
|
||||
| `RUN_SCHD` | **Cron schedule** | input | If `RUN="schedule"` | Cron format: `"0 * * * *"` (hourly) |
|
||||
| `CMD` | **Command/script to execute** | input | **YES** | Linux command or path to script |
|
||||
| `RUN_TIMEOUT` | **Maximum execution time in seconds** | input | optional | Numeric: `"60"`, `"120"`, etc. |
|
||||
|
||||
### Data & Filtering Settings
|
||||
|
||||
| Function | Purpose | Type | Required | Options |
|
||||
|----------|---------|------|----------|---------|
|
||||
| `WATCH` | **Which columns to monitor for changes** | multi-select | optional | Column names from data contract |
|
||||
| `REPORT_ON` | **When to send notifications** | select | optional | `"new"`, `"watched-changed"`, `"watched-not-changed"`, `"missing-in-last-scan"` |
|
||||
| `DB_PATH` | **External database path** | input | If using SQLite plugin | File path: `"/etc/pihole/pihole-FTL.db"` |
|
||||
|
||||
### API & Data Settings
|
||||
|
||||
| Function | Purpose | Type | Required | Options |
|
||||
|----------|---------|------|----------|---------|
|
||||
| `API_SQL` | **Generate API JSON file** | (reserved) | Not implemented | — |
|
||||
|
||||
## Component Types
|
||||
|
||||
### Text Input
|
||||
|
||||
Simple text field for API keys, URLs, thresholds, etc.
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "URL",
|
||||
"type": {
|
||||
"dataType": "string",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "input",
|
||||
"elementOptions": [],
|
||||
"transformers": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": "https://api.example.com",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "API URL"}],
|
||||
"description": [{"language_code": "en_us", "string": "The API endpoint to query"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Password Input
|
||||
|
||||
Secure field with SHA256 hashing transformer.
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "API_KEY",
|
||||
"type": {
|
||||
"dataType": "string",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "input",
|
||||
"elementOptions": [{"type": "password"}],
|
||||
"transformers": ["sha256"]
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": "",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "API Key"}],
|
||||
"description": [{"language_code": "en_us", "string": "Stored securely with SHA256 hashing"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Dropdown/Select
|
||||
|
||||
Choose from predefined options.
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "RUN",
|
||||
"type": {
|
||||
"dataType": "string",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "select",
|
||||
"elementOptions": [],
|
||||
"transformers": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": "disabled",
|
||||
"options": ["disabled", "once", "schedule", "always_after_scan"],
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "When to run"}],
|
||||
"description": [{"language_code": "en_us", "string": "Select execution trigger"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Select
|
||||
|
||||
Select multiple values (returns array).
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "WATCH",
|
||||
"type": {
|
||||
"dataType": "array",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "select",
|
||||
"elementOptions": [{"isMultiSelect": true}],
|
||||
"transformers": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": [],
|
||||
"options": ["Status", "IP_Address", "Response_Time"],
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Watch columns"}],
|
||||
"description": [{"language_code": "en_us", "string": "Which columns trigger notifications on change"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Checkbox
|
||||
|
||||
Boolean toggle.
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "ENABLED",
|
||||
"type": {
|
||||
"dataType": "boolean",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "input",
|
||||
"elementOptions": [{"type": "checkbox"}],
|
||||
"transformers": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": false,
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Enable feature"}],
|
||||
"description": [{"language_code": "en_us", "string": "Toggle this feature on/off"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Textarea
|
||||
|
||||
Multi-line text input.
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "CUSTOM_CONFIG",
|
||||
"type": {
|
||||
"dataType": "string",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "textarea",
|
||||
"elementOptions": [],
|
||||
"transformers": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": "",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Custom Configuration"}],
|
||||
"description": [{"language_code": "en_us", "string": "Enter configuration (one per line)"}]
|
||||
}
|
||||
```
|
||||
|
||||
### Read-Only Label
|
||||
|
||||
Display information without user input.
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "STATUS_DISPLAY",
|
||||
"type": {
|
||||
"dataType": "string",
|
||||
"elements": [
|
||||
{
|
||||
"elementType": "input",
|
||||
"elementOptions": [{"readonly": true}],
|
||||
"transformers": []
|
||||
}
|
||||
]
|
||||
},
|
||||
"default_value": "Ready",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Status"}]
|
||||
}
|
||||
```
|
||||
|
||||
## Using Settings in Your Script
|
||||
|
||||
### Method 1: Via `get_setting_value()` Helper
|
||||
|
||||
**Recommended approach** — clean and simple:
|
||||
|
||||
```python
|
||||
from helper import get_setting_value
|
||||
|
||||
# Read the setting by function name with plugin prefix
|
||||
api_url = get_setting_value('MYPLN_API_URL')
|
||||
api_key = get_setting_value('MYPLN_API_KEY')
|
||||
watch_columns = get_setting_value('MYPLN_WATCH') # Returns list if multi-select
|
||||
|
||||
# Use in your script
|
||||
mylog("none", f"Connecting to {api_url} with key {api_key}")
|
||||
```
|
||||
|
||||
### Method 2: Via Command Parameters
|
||||
|
||||
For more complex scenarios where you need to **pass settings as command-line arguments**:
|
||||
|
||||
Define `params` in your `config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"params": [
|
||||
{
|
||||
"name": "api_url",
|
||||
"type": "setting",
|
||||
"value": "MYPLN_API_URL"
|
||||
},
|
||||
{
|
||||
"name": "timeout",
|
||||
"type": "setting",
|
||||
"value": "MYPLN_RUN_TIMEOUT"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Update your `CMD` setting:
|
||||
|
||||
```json
|
||||
{
|
||||
"function": "CMD",
|
||||
"default_value": "python3 /app/front/plugins/my_plugin/script.py --url={api_url} --timeout={timeout}"
|
||||
}
|
||||
```
|
||||
|
||||
The framework will replace `{api_url}` and `{timeout}` with actual values before execution.
|
||||
|
||||
### Method 3: Via Environment Variables (check with maintainer)
|
||||
|
||||
Settings are also available as environment variables:
|
||||
|
||||
```bash
|
||||
# Environment variable format: <PREFIX>_<FUNCTION>
|
||||
MY_PLUGIN_API_URL
|
||||
MY_PLUGIN_API_KEY
|
||||
MY_PLUGIN_RUN
|
||||
```
|
||||
|
||||
In Python:
|
||||
```python
|
||||
import os
|
||||
|
||||
api_url = os.environ.get('MYPLN_API_URL', 'default_value')
|
||||
```
|
||||
|
||||
## Localized Strings
|
||||
|
||||
Settings and UI text support multiple languages. Define translations in the `name` and `description` arrays:
|
||||
|
||||
```json
|
||||
{
|
||||
"localized": ["name", "description"],
|
||||
"name": [
|
||||
{
|
||||
"language_code": "en_us",
|
||||
"string": "API URL"
|
||||
},
|
||||
{
|
||||
"language_code": "es_es",
|
||||
"string": "URL de API"
|
||||
},
|
||||
{
|
||||
"language_code": "de_de",
|
||||
"string": "API-URL"
|
||||
}
|
||||
],
|
||||
"description": [
|
||||
{
|
||||
"language_code": "en_us",
|
||||
"string": "Enter the API endpoint URL"
|
||||
},
|
||||
{
|
||||
"language_code": "es_es",
|
||||
"string": "Ingrese la URL del endpoint de API"
|
||||
},
|
||||
{
|
||||
"language_code": "de_de",
|
||||
"string": "Geben Sie die API-Endpunkt-URL ein"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
- `en_us` - English (required)
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Website Monitor Plugin
|
||||
|
||||
```json
|
||||
{
|
||||
"settings": [
|
||||
{
|
||||
"function": "RUN",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "disabled",
|
||||
"options": ["disabled", "once", "schedule"],
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "When to run"}],
|
||||
"description": [{"language_code": "en_us", "string": "Enable website monitoring"}]
|
||||
},
|
||||
{
|
||||
"function": "RUN_SCHD",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "*/5 * * * *",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Schedule"}],
|
||||
"description": [{"language_code": "en_us", "string": "Cron format (default: every 5 minutes)"}]
|
||||
},
|
||||
{
|
||||
"function": "CMD",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "python3 /app/front/plugins/website_monitor/script.py urls={urls}",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Command"}],
|
||||
"description": [{"language_code": "en_us", "string": "Command to execute"}]
|
||||
},
|
||||
{
|
||||
"function": "RUN_TIMEOUT",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "60",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Timeout"}],
|
||||
"description": [{"language_code": "en_us", "string": "Maximum execution time in seconds"}]
|
||||
},
|
||||
{
|
||||
"function": "URLS",
|
||||
"type": {"dataType": "array", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": ["https://example.com"],
|
||||
"maxLength": 200,
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "URLs to monitor"}],
|
||||
"description": [{"language_code": "en_us", "string": "One URL per line"}]
|
||||
},
|
||||
{
|
||||
"function": "WATCH",
|
||||
"type": {"dataType": "array", "elements": [{"elementType": "select", "elementOptions": [{"isMultiSelect": true}], "transformers": []}]},
|
||||
"default_value": ["Status_Code"],
|
||||
"options": ["Status_Code", "Response_Time", "Certificate_Expiry"],
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Watch columns"}],
|
||||
"description": [{"language_code": "en_us", "string": "Which changes trigger notifications"}]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: PiHole Integration Plugin
|
||||
|
||||
```json
|
||||
{
|
||||
"settings": [
|
||||
{
|
||||
"function": "RUN",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "select", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "disabled",
|
||||
"options": ["disabled", "schedule"],
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "When to run"}],
|
||||
"description": [{"language_code": "en_us", "string": "Enable PiHole integration"}]
|
||||
},
|
||||
{
|
||||
"function": "DB_PATH",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [], "transformers": []}]},
|
||||
"default_value": "/etc/pihole/pihole-FTL.db",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "Database path"}],
|
||||
"description": [{"language_code": "en_us", "string": "Path to pihole-FTL.db inside container"}]
|
||||
},
|
||||
{
|
||||
"function": "API_KEY",
|
||||
"type": {"dataType": "string", "elements": [{"elementType": "input", "elementOptions": [{"type": "password"}], "transformers": ["sha256"]}]},
|
||||
"default_value": "",
|
||||
"localized": ["name", "description"],
|
||||
"name": [{"language_code": "en_us", "string": "API Key"}],
|
||||
"description": [{"language_code": "en_us", "string": "PiHole API key (optional, stored securely)"}]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Validation & Testing
|
||||
|
||||
### Check Settings Are Recognized
|
||||
|
||||
After saving your `config.json`:
|
||||
|
||||
1. Restart the backend: Run task `[Dev Container] Start Backend (Python)`
|
||||
2. Open Settings page in UI
|
||||
3. Navigate to Plugin Settings
|
||||
4. Look for your plugin's settings
|
||||
|
||||
### Read Setting Values in Script
|
||||
|
||||
Test that values are accessible:
|
||||
|
||||
```python
|
||||
from helper import get_setting_value
|
||||
|
||||
# Try to read a setting
|
||||
value = get_setting_value('MYPLN_API_URL')
|
||||
mylog('none', f"Setting value: {value}")
|
||||
|
||||
# Should print the user-configured value or default
|
||||
```
|
||||
|
||||
### Debug Settings
|
||||
|
||||
Check backend logs:
|
||||
|
||||
```bash
|
||||
tail -f /tmp/log/stdout.log | grep -i "setting\|MYPLN"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Settings System Documentation](./SETTINGS_SYSTEM.md) - Full settings flow and lifecycle
|
||||
- [Quick Start Guide](PLUGINS_DEV_QUICK_START.md) - Get a working plugin quickly
|
||||
- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) - Output data format
|
||||
- [UI Components](PLUGINS_DEV_UI_COMPONENTS.md) - Display plugin results
|
||||
642
docs/PLUGINS_DEV_UI_COMPONENTS.md
Normal file
642
docs/PLUGINS_DEV_UI_COMPONENTS.md
Normal file
@@ -0,0 +1,642 @@
|
||||
# Plugin UI Components
|
||||
|
||||
Configure how your plugin's data is displayed in the NetAlertX web interface.
|
||||
|
||||
## Overview
|
||||
|
||||
Plugin results are displayed in the UI via the **Plugins page** and **Device details tabs**. You control the appearance and functionality of these displays by defining `database_column_definitions` in your plugin's `config.json`.
|
||||
|
||||
Each column definition specifies:
|
||||
- Which data field to display
|
||||
- How to render it (label, link, color-coded badge, etc.)
|
||||
- What CSS classes to apply
|
||||
- What transformations to apply (regex, string replacement, etc.)
|
||||
|
||||
## Column Definition Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Object_PrimaryID",
|
||||
"mapped_to_column": "devMac",
|
||||
"mapped_to_column_data": null,
|
||||
"css_classes": "col-sm-2",
|
||||
"show": true,
|
||||
"type": "device_mac",
|
||||
"default_value": "",
|
||||
"options": [],
|
||||
"options_params": [],
|
||||
"localized": ["name"],
|
||||
"name": [
|
||||
{
|
||||
"language_code": "en_us",
|
||||
"string": "MAC Address"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Properties
|
||||
|
||||
| Property | Type | Required | Description |
|
||||
|----------|------|----------|-------------|
|
||||
| `column` | string | **YES** | Source column name from data contract (e.g., `Object_PrimaryID`, `Watched_Value1`) |
|
||||
| `mapped_to_column` | string | no | Target database column if mapping to a table like `CurrentScan` |
|
||||
| `mapped_to_column_data` | object | no | Static value to map instead of using column data |
|
||||
| `css_classes` | string | no | Bootstrap CSS classes for width/spacing (e.g., `"col-sm-2"`, `"col-sm-6"`) |
|
||||
| `show` | boolean | **YES** | Whether to display in UI (must be `true` to appear) |
|
||||
| `type` | string | **YES** | How to render the value (see [Render Types](#render-types)) |
|
||||
| `default_value` | varies | **YES** | Default if column is empty |
|
||||
| `options` | array | no | Options for `select`/`threshold`/`replace`/`regex` types |
|
||||
| `options_params` | array | no | Dynamic options from SQL or settings |
|
||||
| `localized` | array | **YES** | Which properties need translations (e.g., `["name", "description"]`) |
|
||||
| `name` | array | **YES** | Display name in UI (localized strings) |
|
||||
| `description` | array | no | Help text in UI (localized strings) |
|
||||
| `maxLength` | number | no | Character limit for input fields |
|
||||
|
||||
## Render Types
|
||||
|
||||
### Display-Only Types
|
||||
|
||||
These render as read-only display elements:
|
||||
|
||||
#### `label`
|
||||
Plain text display (read-only).
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"show": true,
|
||||
"type": "label",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Status"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Output:** `online`
|
||||
|
||||
---
|
||||
|
||||
#### `device_mac`
|
||||
Renders as a clickable link to the device with the given MAC address.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "ForeignKey",
|
||||
"show": true,
|
||||
"type": "device_mac",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Device"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Input:** `aa:bb:cc:dd:ee:ff`
|
||||
**Output:** Clickable link to device details page
|
||||
|
||||
---
|
||||
|
||||
#### `device_ip`
|
||||
Resolves an IP address to a MAC address and creates a device link.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Object_SecondaryID",
|
||||
"show": true,
|
||||
"type": "device_ip",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Host"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Input:** `192.168.1.100`
|
||||
**Output:** Link to device with that IP (if known)
|
||||
|
||||
---
|
||||
|
||||
#### `device_name_mac`
|
||||
Creates a device link with the target device's name as the link label.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Object_PrimaryID",
|
||||
"show": true,
|
||||
"type": "device_name_mac",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Device Name"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Input:** `aa:bb:cc:dd:ee:ff`
|
||||
**Output:** Device name (clickable link to device)
|
||||
|
||||
---
|
||||
|
||||
#### `url`
|
||||
Renders as a clickable HTTP/HTTPS link.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"show": true,
|
||||
"type": "url",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Endpoint"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Input:** `https://example.com/api`
|
||||
**Output:** Clickable link
|
||||
|
||||
---
|
||||
|
||||
#### `url_http_https`
|
||||
Creates two links (HTTP and HTTPS) as lock icons for the given IP/hostname.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Object_SecondaryID",
|
||||
"show": true,
|
||||
"type": "url_http_https",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Web Links"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Input:** `192.168.1.50`
|
||||
**Output:** 🔓 HTTP link | 🔒 HTTPS link
|
||||
|
||||
---
|
||||
|
||||
#### `textarea_readonly`
|
||||
Multi-line read-only display with newlines preserved.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Extra",
|
||||
"show": true,
|
||||
"type": "textarea_readonly",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Details"}]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Interactive Types
|
||||
|
||||
#### `textbox_save`
|
||||
User-editable text box that persists changes to the database (typically `UserData` column).
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "UserData",
|
||||
"show": true,
|
||||
"type": "textbox_save",
|
||||
"default_value": "",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Notes"}]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Styled/Transformed Types
|
||||
|
||||
#### `label` with `threshold`
|
||||
Color-codes values based on ranges. Useful for status codes, latency, capacity percentages.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"show": true,
|
||||
"type": "threshold",
|
||||
"options": [
|
||||
{
|
||||
"maximum": 199,
|
||||
"hexColor": "#792D86" // Purple for <199
|
||||
},
|
||||
{
|
||||
"maximum": 299,
|
||||
"hexColor": "#5B862D" // Green for 200-299
|
||||
},
|
||||
{
|
||||
"maximum": 399,
|
||||
"hexColor": "#7D862D" // Orange for 300-399
|
||||
},
|
||||
{
|
||||
"maximum": 499,
|
||||
"hexColor": "#BF6440" // Red-orange for 400-499
|
||||
},
|
||||
{
|
||||
"maximum": 999,
|
||||
"hexColor": "#D33115" // Dark red for 500+
|
||||
}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "HTTP Status"}]
|
||||
}
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
- Value `150` → Purple (≤199)
|
||||
- Value `250` → Green (≤299)
|
||||
- Value `350` → Orange (≤399)
|
||||
- Value `450` → Red-orange (≤499)
|
||||
- Value `550` → Dark red (>500)
|
||||
|
||||
---
|
||||
|
||||
#### `replace`
|
||||
Replaces specific values with display strings or HTML.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value2",
|
||||
"show": true,
|
||||
"type": "replace",
|
||||
"options": [
|
||||
{
|
||||
"equals": "online",
|
||||
"replacement": "<i class='fa-solid fa-circle' style='color: green;'></i> Online"
|
||||
},
|
||||
{
|
||||
"equals": "offline",
|
||||
"replacement": "<i class='fa-solid fa-circle' style='color: red;'></i> Offline"
|
||||
},
|
||||
{
|
||||
"equals": "idle",
|
||||
"replacement": "<i class='fa-solid fa-circle' style='color: yellow;'></i> Idle"
|
||||
}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Status"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Output Examples:**
|
||||
- `"online"` → 🟢 Online
|
||||
- `"offline"` → 🔴 Offline
|
||||
- `"idle"` → 🟡 Idle
|
||||
|
||||
---
|
||||
|
||||
#### `regex`
|
||||
Applies a regular expression to extract/transform values.
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"show": true,
|
||||
"type": "regex",
|
||||
"options": [
|
||||
{
|
||||
"type": "regex",
|
||||
"param": "([0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3})"
|
||||
}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "IP Address"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Input:** `Host: 192.168.1.100 Port: 8080`
|
||||
**Output:** `192.168.1.100`
|
||||
|
||||
---
|
||||
|
||||
#### `eval`
|
||||
Evaluates JavaScript code with access to the column value (use `${value}` or `{value}`).
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"show": true,
|
||||
"type": "eval",
|
||||
"default_value": "",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Formatted Value"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Example with custom formatting:**
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"show": true,
|
||||
"type": "eval",
|
||||
"options": [
|
||||
{
|
||||
"type": "eval",
|
||||
"param": "`<b>${value}</b> units`"
|
||||
}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Value with Units"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Input:** `42`
|
||||
**Output:** **42** units
|
||||
|
||||
---
|
||||
|
||||
### Chaining Types
|
||||
|
||||
You can chain multiple transformations with dot notation:
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value3",
|
||||
"show": true,
|
||||
"type": "regex.url_http_https",
|
||||
"options": [
|
||||
{
|
||||
"type": "regex",
|
||||
"param": "([\\d.:]+)" // Extract IP/host
|
||||
}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "HTTP/S Links"}]
|
||||
}
|
||||
```
|
||||
|
||||
**Flow:**
|
||||
1. Apply regex to extract `192.168.1.50` from input
|
||||
2. Create HTTP/HTTPS links for that host
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Options
|
||||
|
||||
### SQL-Driven Select
|
||||
|
||||
Use SQL query results to populate dropdown options:
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value2",
|
||||
"show": true,
|
||||
"type": "select",
|
||||
"options": ["{value}"],
|
||||
"options_params": [
|
||||
{
|
||||
"name": "value",
|
||||
"type": "sql",
|
||||
"value": "SELECT devType as id, devType as name FROM Devices UNION SELECT 'Unknown' as id, 'Unknown' as name ORDER BY id"
|
||||
}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Device Type"}]
|
||||
}
|
||||
```
|
||||
|
||||
The SQL query must return exactly **2 columns:**
|
||||
- **First column (id):** Option value
|
||||
- **Second column (name):** Display label
|
||||
|
||||
---
|
||||
|
||||
### Setting-Driven Select
|
||||
|
||||
Use plugin settings to populate options:
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"show": true,
|
||||
"type": "select",
|
||||
"options": ["{value}"],
|
||||
"options_params": [
|
||||
{
|
||||
"name": "value",
|
||||
"type": "setting",
|
||||
"value": "MYPLN_AVAILABLE_STATUSES"
|
||||
}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Status"}]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mapping to Database Tables
|
||||
|
||||
### Mapping to `CurrentScan`
|
||||
|
||||
To import plugin data into the device scan pipeline (for notifications, heuristics, etc.):
|
||||
|
||||
1. Add `"mapped_to_table": "CurrentScan"` at the root level of `config.json`
|
||||
2. Add `"mapped_to_column"` property to each column definition
|
||||
|
||||
```json
|
||||
{
|
||||
"code_name": "my_device_scanner",
|
||||
"unique_prefix": "MYSCAN",
|
||||
"mapped_to_table": "CurrentScan",
|
||||
"database_column_definitions": [
|
||||
{
|
||||
"column": "Object_PrimaryID",
|
||||
"mapped_to_column": "cur_MAC",
|
||||
"show": true,
|
||||
"type": "device_mac",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "MAC Address"}]
|
||||
},
|
||||
{
|
||||
"column": "Object_SecondaryID",
|
||||
"mapped_to_column": "cur_IP",
|
||||
"show": true,
|
||||
"type": "device_ip",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "IP Address"}]
|
||||
},
|
||||
{
|
||||
"column": "NameDoesntMatter",
|
||||
"mapped_to_column": "cur_ScanMethod",
|
||||
"mapped_to_column_data": {
|
||||
"value": "MYSCAN"
|
||||
},
|
||||
"show": true,
|
||||
"type": "label",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Scan Method"}]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Using Static Values
|
||||
|
||||
Use `mapped_to_column_data` to map a static value instead of reading from a column:
|
||||
|
||||
```json
|
||||
{
|
||||
"column": "NameDoesntMatter",
|
||||
"mapped_to_column": "cur_ScanMethod",
|
||||
"mapped_to_column_data": {
|
||||
"value": "MYSCAN"
|
||||
},
|
||||
"show": true,
|
||||
"type": "label",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Discovery Method"}]
|
||||
}
|
||||
```
|
||||
|
||||
This always sets `cur_ScanMethod` to `"MYSCAN"` regardless of column data.
|
||||
|
||||
---
|
||||
|
||||
## Filters
|
||||
|
||||
Control which rows are displayed based on filter conditions. Filters are applied on the client-side in JavaScript.
|
||||
|
||||
```json
|
||||
{
|
||||
"data_filters": [
|
||||
{
|
||||
"compare_column": "Object_PrimaryID",
|
||||
"compare_operator": "==",
|
||||
"compare_field_id": "txtMacFilter",
|
||||
"compare_js_template": "'{value}'.toString()",
|
||||
"compare_use_quotes": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Property | Description |
|
||||
|----------|-------------|
|
||||
| `compare_column` | The column from plugin results to compare (left side) |
|
||||
| `compare_operator` | JavaScript operator: `==`, `!=`, `<`, `>`, `<=`, `>=`, `includes`, `startsWith` |
|
||||
| `compare_field_id` | HTML input field ID containing the filter value (right side) |
|
||||
| `compare_js_template` | JavaScript template to transform values. Use `{value}` placeholder |
|
||||
| `compare_use_quotes` | If `true`, wrap result in quotes for string comparison |
|
||||
|
||||
**Example: Filter by MAC address**
|
||||
|
||||
```json
|
||||
{
|
||||
"data_filters": [
|
||||
{
|
||||
"compare_column": "ForeignKey",
|
||||
"compare_operator": "==",
|
||||
"compare_field_id": "txtMacFilter",
|
||||
"compare_js_template": "'{value}'.toString()",
|
||||
"compare_use_quotes": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
When viewing a device detail page, the `txtMacFilter` field is populated with that device's MAC, and only rows where `ForeignKey == MAC` are shown.
|
||||
|
||||
---
|
||||
|
||||
## Example: Complete Column Definitions
|
||||
|
||||
```json
|
||||
{
|
||||
"database_column_definitions": [
|
||||
{
|
||||
"column": "Object_PrimaryID",
|
||||
"mapped_to_column": "cur_MAC",
|
||||
"css_classes": "col-sm-2",
|
||||
"show": true,
|
||||
"type": "device_mac",
|
||||
"default_value": "",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "MAC Address"}]
|
||||
},
|
||||
{
|
||||
"column": "Object_SecondaryID",
|
||||
"mapped_to_column": "cur_IP",
|
||||
"css_classes": "col-sm-2",
|
||||
"show": true,
|
||||
"type": "device_ip",
|
||||
"default_value": "unknown",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "IP Address"}]
|
||||
},
|
||||
{
|
||||
"column": "DateTime",
|
||||
"css_classes": "col-sm-2",
|
||||
"show": true,
|
||||
"type": "label",
|
||||
"default_value": "",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Last Seen"}]
|
||||
},
|
||||
{
|
||||
"column": "Watched_Value1",
|
||||
"css_classes": "col-sm-2",
|
||||
"show": true,
|
||||
"type": "threshold",
|
||||
"options": [
|
||||
{"maximum": 199, "hexColor": "#792D86"},
|
||||
{"maximum": 299, "hexColor": "#5B862D"},
|
||||
{"maximum": 399, "hexColor": "#7D862D"},
|
||||
{"maximum": 499, "hexColor": "#BF6440"},
|
||||
{"maximum": 999, "hexColor": "#D33115"}
|
||||
],
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "HTTP Status"}]
|
||||
},
|
||||
{
|
||||
"column": "Watched_Value2",
|
||||
"css_classes": "col-sm-1",
|
||||
"show": true,
|
||||
"type": "label",
|
||||
"default_value": "",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Response Time"}]
|
||||
},
|
||||
{
|
||||
"column": "Extra",
|
||||
"css_classes": "col-sm-3",
|
||||
"show": true,
|
||||
"type": "textarea_readonly",
|
||||
"default_value": "",
|
||||
"localized": ["name"],
|
||||
"name": [{"language_code": "en_us", "string": "Additional Info"}]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS Classes
|
||||
|
||||
Use Bootstrap grid classes to control column widths in tables:
|
||||
|
||||
| Class | Width | Usage |
|
||||
|-------|-------|-------|
|
||||
| `col-sm-1` | ~8% | Very narrow (icons, status) |
|
||||
| `col-sm-2` | ~16% | Narrow (MACs, IPs) |
|
||||
| `col-sm-3` | ~25% | Medium (names, URLs) |
|
||||
| `col-sm-4` | ~33% | Medium-wide (descriptions) |
|
||||
| `col-sm-6` | ~50% | Wide (large content) |
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] All columns have `"show": true` or `false`
|
||||
- [ ] Display columns with `"type"` specified from supported types
|
||||
- [ ] Localized strings include at least `en_us`
|
||||
- [ ] `mapped_to_column` matches target table schema (if using mapping)
|
||||
- [ ] Options/thresholds have correct structure
|
||||
- [ ] CSS classes are valid Bootstrap grid classes
|
||||
- [ ] Chaining types (e.g., `regex.url_http_https`) are supported combinations
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Plugin Data Contract](PLUGINS_DEV_DATA_CONTRACT.md) - What data fields are available
|
||||
- [Plugin Settings System](PLUGINS_DEV_SETTINGS.md) - Configure user input
|
||||
- [Database Mapping](PLUGINS_DEV.md#-mapping-the-plugin-results-into-a-database-table) - Map data to core tables
|
||||
- [Debugging Plugins](DEBUG_PLUGINS.md) - Troubleshoot display issues
|
||||
@@ -1,5 +1,9 @@
|
||||
# Reverse Proxy Configuration
|
||||
|
||||
> [!NOTE]
|
||||
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
|
||||
|
||||
|
||||
> [!TIP]
|
||||
> You will need to specify the `BACKEND_API_URL` setting if you are running reverse proxies. This is the URL that points to the backend server url (including your `GRAPHQL_PORT`)
|
||||
>
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
## ⚙ Setting system
|
||||
|
||||
This is an explanation how settings are handled intended for anyone thinking about writing their own plugin or contributing to the project.
|
||||
This is an explanation how settings are handled intended for anyone thinking about writing their own plugin or contributing to the project.
|
||||
|
||||
If you are a user of the app, settings have a detailed description in the _Settings_ section of the app. Open an issue if you'd like to clarify any of the settings.
|
||||
If you are a user of the app, settings have a detailed description in the _Settings_ section of the app. Open an issue if you'd like to clarify any of the settings.
|
||||
|
||||
### 🛢 Data storage
|
||||
|
||||
The source of truth for user-defined values is the `app.conf` file. Editing the file makes the App overwrite values in the `Settings` database table and in the `table_settings.json` file.
|
||||
The source of truth for user-defined values is the `app.conf` file. Editing the file makes the App overwrite values in the `Settings` database table and in the `table_settings.json` file.
|
||||
|
||||
#### Settings database table
|
||||
|
||||
The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](./DATABASE.md).
|
||||
The `Settings` database table contains settings for App run purposes. The table is recreated every time the App restarts. The settings are loaded from the source-of-truth, that is the `app.conf` file. A high-level overview on the database structure can be found in the [database documentation](./DATABASE.md).
|
||||
|
||||
#### table_settings.json
|
||||
|
||||
@@ -22,23 +22,23 @@ The json file is also cached on the client-side local storage of the browser.
|
||||
|
||||
#### app.conf
|
||||
|
||||
> [!NOTE]
|
||||
> [!NOTE]
|
||||
> This is the source of truth for settings. User-defined values in this files always override default values specified in the Plugin definition.
|
||||
|
||||
The App generates two `app.conf` entries for every setting (Since version 23.8+). One entry is the setting value, the second is the `__metadata` associated with the setting. This `__metadata` entry contains the full setting definition in JSON format. Currently unused, but intended to be used in future to extend the Settings system.
|
||||
|
||||
#### Plugin settings
|
||||
|
||||
> [!NOTE]
|
||||
> [!NOTE]
|
||||
> This is the preferred way adding settings going forward. I'll be likely migrating all app settings into plugin-based settings.
|
||||
|
||||
Plugin settings are loaded dynamically from the `config.json` of individual plugins. If a setting isn't defined in the `app.conf` file, it is initialized via the `default_value` property of a setting from the `config.json` file. Check the [Plugins documentation](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md#-setting-object-structure), section `⚙ Setting object structure` for details on the structure of the setting.
|
||||
Plugin settings are loaded dynamically from the `config.json` of individual plugins. If a setting isn't defined in the `app.conf` file, it is initialized via the `default_value` property of a setting from the `config.json` file. Check the [Plugins documentation](https://docs.netalertx.com/PLUGINS#-setting-object-structure), section `⚙ Setting object structure` for details on the structure of the setting.
|
||||
|
||||
![Screen 1][screen1]
|
||||
|
||||
### Settings Process flow
|
||||
|
||||
The process flow is mostly managed by the [initialise.py](/server/initialise.py) file.
|
||||
The process flow is mostly managed by the [initialise.py](/server/initialise.py) file.
|
||||
|
||||
The script is responsible for reading user-defined values from a configuration file (`app.conf`), initializing settings, and importing them into a database. It also handles plugins and their configurations.
|
||||
|
||||
|
||||
@@ -1,7 +1,11 @@
|
||||
# Webhook Secrets
|
||||
|
||||
> [!NOTE]
|
||||
> You need to enable the `WEBHOOK` plugin first in order to follow this guide. See the [Plugins guide](./PLUGINS.md) for details.
|
||||
> This is community-contributed. Due to environment, setup, or networking differences, results may vary. Please open a PR to improve it instead of creating an issue, as the maintainer is not actively maintaining it.
|
||||
|
||||
|
||||
> [!NOTE]
|
||||
> You need to enable the `WEBHOOK` plugin first in order to follow this guide. See the [Plugins guide](./PLUGINS.md) for details.
|
||||
|
||||
## How does the signing work?
|
||||
|
||||
@@ -39,3 +43,5 @@ If your implementation is correct, the signature you generated should match the
|
||||
If you want to learn more about webhook security, take a look at [GitHub's webhook documentation](https://docs.github.com/en/webhooks/about-webhooks).
|
||||
|
||||
You can find examples for validating a webhook delivery [here](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries#examples).
|
||||
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
## Issue Description
|
||||
|
||||
NetAlertX automatically detects the legacy `aufs` storage driver, which is commonly found on older Synology NAS devices (DSM 6.x/7.0.x) or Linux systems where the underlying filesystem lacks `d_type` support. This occurs on older ext4 and other filesystems which did not support capabilites at time of last formatting. While ext4 currently support capabilities and filesystem overlays, older variants of ext4 did not and require a reformat to enable the support. Old variants result in docker choosing `aufs` and newer may use `overlayfs`.
|
||||
NetAlertX automatically detects the legacy `aufs` storage driver, which is commonly found on older Synology NAS devices (DSM 6.x/7.0.x) or Linux systems where the underlying filesystem lacks `d_type` support. This occurs on older ext4 and other filesystems which did not support capabilites at time of last formatting. While ext4 currently support capabilities and filesystem overlays, older variants of ext4 did not and require a reformat to enable the support. Old variants result in docker choosing `aufs` and newer may use `overlayfs`.
|
||||
|
||||
**The Technical Limitation:**
|
||||
AUFS (Another Union File System) does not support or preserve extended file attributes (`xattrs`) during Docker image extraction. NetAlertX relies on these attributes to grant granular privileges (`CAP_NET_RAW` and `CAP_NET_ADMIN`) to network scanning binaries like `arp-scan`, `nmap`, and `nbtscan`.
|
||||
@@ -27,7 +27,7 @@ The container is designed to inspect the runtime environment at startup (`/root-
|
||||
### Warning Log
|
||||
When AUFS is detected without root privileges, the system emits the following warning during startup:
|
||||
> ⚠️ WARNING: Reduced functionality (AUFS + non-root user).
|
||||
>
|
||||
>
|
||||
> AUFS strips Linux file capabilities, so tools like arp-scan, nmap, and nbtscan fail when NetAlertX runs as a non-root PUID.
|
||||
>
|
||||
> **Action:** Set PUID=0 on AUFS hosts for full functionality.
|
||||
@@ -162,6 +162,6 @@ docker run --rm -e NETALERTX_PROC_MOUNTS_B64="bm9uZSAvIGF1ZnMgcncs..." netalertx
|
||||
|
||||
* **Docker Storage Drivers:** [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)
|
||||
* **Synology Docker Guide:** [Synology Docker Storage Drivers](https://www.google.com/search?q=https://kb.synology.com/en-global/DSM/tutorial/How_to_use_Docker_on_Synology_NAS)
|
||||
* **Configuration Guidance:** [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
* **Configuration Guidance:** [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
|
||||
|
||||
|
||||
@@ -29,4 +29,4 @@ Limit capabilities to only those required:
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -24,4 +24,4 @@ Fix permissions on the host system for the mounted directories:
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -27,5 +27,5 @@ Option B: Run with a custom UID/GID
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- Default compose and tmpfs guidance: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
- General Docker install and runtime notes: [DOCKER_INSTALLATION.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_INSTALLATION.md)
|
||||
- Default compose and tmpfs guidance: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
- General Docker install and runtime notes: [DOCKER_INSTALLATION.md](https://docs.netalertx.com/DOCKER_INSTALLATION)
|
||||
@@ -29,7 +29,7 @@ Add the required capabilities to your container:
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
|
||||
## CAP_CHOWN required when cap_drop: [ALL]
|
||||
|
||||
|
||||
@@ -33,4 +33,4 @@ volumes:
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -24,4 +24,4 @@ Enable host networking mode:
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -33,4 +33,4 @@ If you don't need a custom port, simply omit the PORT environment variable and t
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -83,4 +83,4 @@ services:
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -24,4 +24,4 @@ Enable read-only mode:
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -26,4 +26,4 @@ After making these changes, restart the container. The application will automati
|
||||
|
||||
Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.
|
||||
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)
|
||||
For detailed Docker Compose configuration guidance, see: [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
hide:
|
||||
- navigation
|
||||
- toc
|
||||
---
|
||||
|
||||
# NetAlertX Documentation
|
||||
|
||||
Welcome to the official NetAlertX documentation! NetAlertX is a powerful tool designed to simplify the management and monitoring of your network. Below, you will find guides and resources to help you set up, configure, and troubleshoot your NetAlertX instance.
|
||||
@@ -15,7 +21,7 @@ NetAlertX provides contextual help within the application:
|
||||
|
||||
## Installation Guides
|
||||
|
||||
The app can be installed different ways, with the best support of the docker-based deployments. This includes the Home Assistant and Unraid installation approaches. See details below.
|
||||
The app can be installed different ways, with the best support of the docker-based deployments. This includes the Home Assistant and Unraid installation approaches. See details below.
|
||||
|
||||
### Docker (Fully Supported)
|
||||
|
||||
@@ -29,13 +35,13 @@ This guide will take you through the process of setting up NetAlertX using Docke
|
||||
|
||||
You can install NetAlertX also as a Home Assistant addon [](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Falexbelgium%2Fhassio-addons) via the [alexbelgium/hassio-addons](https://github.com/alexbelgium/hassio-addons/) repository. This is only possible if you run a supervised instance of Home Assistant. If not, you can still run NetAlertX in a separate Docker container and follow this guide to configure MQTT.
|
||||
|
||||
- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
|
||||
- [[Installation] Home Assistant](https://github.com/alexbelgium/hassio-addons/tree/master/netalertx)
|
||||
|
||||
### Unraid (Partial Support)
|
||||
|
||||
The Unraid template was created by the community, so it's only partially supported. Alternatively, here is [another version of the Unraid template](https://github.com/jokob-sk/NetAlertX-unraid).
|
||||
The Unraid template was created by the community, so it's only partially supported. Alternatively, here is [another version of the Unraid template](https://github.com/jokob-sk/NetAlertX-unraid).
|
||||
|
||||
- [[Installation] Unraid App](https://unraid.net/community/apps)
|
||||
- [[Installation] Unraid App](https://unraid.net/community/apps)
|
||||
|
||||
### Bare-Metal Installation (Experimental)
|
||||
|
||||
@@ -55,7 +61,7 @@ If you need help or run into issues, here are some resources to guide you:
|
||||
- [Check common issues](./DEBUG_TIPS.md#common-issues) to see if your problem has already been reported.
|
||||
- [Look at closed issues](https://github.com/jokob-sk/NetAlertX/issues?q=is%3Aissue+is%3Aclosed) for possible solutions to past problems.
|
||||
- **Enable debugging** to gather more information: [Debug Guide](./DEBUG_TIPS.md).
|
||||
|
||||
|
||||
**Need more help?** Join the community discussions or submit a support request:
|
||||
|
||||
- Visit the [GitHub Discussions](https://github.com/jokob-sk/NetAlertX/discussions) for community support.
|
||||
|
||||
Reference in New Issue
Block a user