From b9ef9ad04182acc3f8a82c9cf787488870ef1c02 Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 26 Nov 2025 09:25:37 +1100 Subject: [PATCH 01/34] DOCS: tmpfs cleanup Signed-off-by: jokob-sk --- README.md | 60 ++++++------ docs/DEBUG_TIPS.md | 44 ++++++--- docs/DOCKER_INSTALLATION.md | 48 +++++----- docs/DOCKER_PORTAINER.md | 34 +++---- docs/DOCKER_SWARM.md | 10 +- docs/FILE_PERMISSIONS.md | 21 +++-- docs/MIGRATION.md | 179 ++++++++++++++++++------------------ docs/PERFORMANCE.md | 103 ++++++++++++--------- docs/REVERSE_DNS.md | 37 ++------ docs/REVERSE_PROXY.md | 129 +++++++++++++------------- docs/SYNOLOGY_GUIDE.md | 42 ++++++--- mkdocs.yml | 33 +++---- 12 files changed, 378 insertions(+), 362 deletions(-) diff --git a/README.md b/README.md index 3ec4f3a6..0b39e673 100755 --- a/README.md +++ b/README.md @@ -34,20 +34,22 @@ Get visibility of what's going on on your WIFI/LAN network and enable presence d ## 🚀 Quick Start > [!WARNING] -> ⚠ **Important:** The documentation has been recently updated and some instructions may have changed. -> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container. +> ⚠ **Important:** The documentation has been recently updated and some instructions may have changed. +> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container. > These docs reflect the latest development version and may differ from the production image. Start NetAlertX in seconds with Docker: ```bash -docker run -d --rm --network=host \ +docker run -d \ + --network=host \ + --restart unless-stopped \ -v /local_data_dir/config:/data/config \ -v /local_data_dir/db:/data/db \ - -v /etc/localtime:/etc/localtime \ - --mount type=tmpfs,target=/tmp/api \ + -v /etc/localtime:/etc/localtime:ro \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ -e PORT=20211 \ - -e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \ + -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \ ghcr.io/jokob-sk/netalertx:latest ``` @@ -67,9 +69,9 @@ For other install methods, check the [installation docs](#-documentation) | [📑 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) -|----------------------| ----------------------| ----------------------| ----------------------| ----------------------| +|----------------------| ----------------------| ----------------------| ----------------------| ----------------------| -![showcase][showcase] +![showcase][showcase]
📷 Click for more screenshots @@ -87,15 +89,15 @@ For other install methods, check the [installation docs](#-documentation) ### Scanners -The app scans your network for **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Discovery & scan methods include: **arp-scan**, **Pi-hole - DB import**, **Pi-hole - DHCP leases import**, **Generic DHCP leases import**, **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) docs for a full list of avaliable plugins. +The app scans your network for **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Discovery & scan methods include: **arp-scan**, **Pi-hole - DB import**, **Pi-hole - DHCP leases import**, **Generic DHCP leases import**, **UNIFI controller import**, **SNMP-enabled router import**. Check the [Plugins](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) docs for a full list of avaliable plugins. ### Notification gateways -Send notifications to more than 80+ services, including Telegram via [Apprise](https://hub.docker.com/r/caronc/apprise), or use native [Pushsafer](https://www.pushsafer.com/), [Pushover](https://www.pushover.net/), or [NTFY](https://ntfy.sh/) publishers. +Send notifications to more than 80+ services, including Telegram via [Apprise](https://hub.docker.com/r/caronc/apprise), or use native [Pushsafer](https://www.pushsafer.com/), [Pushover](https://www.pushover.net/), or [NTFY](https://ntfy.sh/) publishers. ### Integrations and Plugins -Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md), read [API endpoints](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md), or use [Webhooks](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WEBHOOK_N8N.md) to setup custom automation flows. You can also +Feed your data and device changes into [Home Assistant](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HOME_ASSISTANT.md), read [API endpoints](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md), or use [Webhooks](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WEBHOOK_N8N.md) to setup custom automation flows. You can also build your own scanners with the [Plugin system](https://github.com/jokob-sk/NetAlertX/tree/main/docs/PLUGINS.md#readme) in as little as [15 minutes](https://www.youtube.com/watch?v=cdbxlwiWhv8). ### Workflows @@ -108,10 +110,10 @@ The [workflows module](https://github.com/jokob-sk/NetAlertX/blob/main/docs/WORK Supported browsers: Chrome, Firefox -- [[Installation] Docker](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] Bare metal](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) -- [[Installation] Unraid App](https://unraid.net/community/apps) +- [[Installation] Docker](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] Bare metal](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) +- [[Installation] Unraid App](https://unraid.net/community/apps) - [[Setup] Usage and Configuration](https://github.com/jokob-sk/NetAlertX/blob/main/docs/README.md) - [[Development] API docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) - [[Development] Custom Plugins](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS_DEV.md) @@ -132,19 +134,19 @@ See [Security Best Practices](https://github.com/jokob-sk/NetAlertX/security) fo ## ❓ FAQ -**Q: Why don’t I see any devices?** +**Q: Why don’t I see any devices?** A: Ensure the container has proper network access (e.g., use `--network host` on Linux). Also check that your scan method is properly configured in the UI. -**Q: Does this work on Wi-Fi-only devices like Raspberry Pi?** +**Q: Does this work on Wi-Fi-only devices like Raspberry Pi?** A: Yes, but some scanners (e.g. ARP) work best on Ethernet. For Wi-Fi, try SNMP, DHCP, or Pi-hole import. -**Q: Will this send any data to the internet?** +**Q: Will this send any data to the internet?** A: No. All scans and data remain local, unless you set up cloud-based notifications. -**Q: Can I use this without Docker?** +**Q: Can I use this without Docker?** A: Yes! You can install it bare-metal. See the [bare metal installation guide](https://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md). -**Q: Where is the data stored?** +**Q: Where is the data stored?** A: In the `/data/config` and `/data/db` folders. Back up these folders regularly. @@ -162,9 +164,9 @@ Check the [GitHub Issues](https://github.com/jokob-sk/NetAlertX/issues) for the ### 📧 Get notified what's new -Get notified about a new release, what new functionality you can use and about breaking changes. +Get notified about a new release, what new functionality you can use and about breaking changes. -![Follow and star][follow_star] +![Follow and star][follow_star] ### 🔀 Other Alternative Apps @@ -175,15 +177,15 @@ Get notified about a new release, what new functionality you can use and about b ### 💙 Donations -Thank you to everyone who appreciates this tool and donates. +Thank you to everyone who appreciates this tool and donates.
Click for more ways to donate - +
- | [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) | [![Patreon](https://i.imgur.com/MuYsrq1.png)](https://www.patreon.com/user?u=84385063) | -| --- | --- | --- | + | [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) | [![Patreon](https://i.imgur.com/MuYsrq1.png)](https://www.patreon.com/user?u=84385063) | +| --- | --- | --- | - Bitcoin: `1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM` - Ethereum: `0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7` @@ -194,11 +196,11 @@ Thank you to everyone who appreciates this tool and donates. ### 🏗 Contributors -This project would be nothing without the amazing work of the community, with special thanks to: +This project would be nothing without the amazing work of the community, with special thanks to: -> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up), [vladaurosh](https://github.com/vladaurosh) for Alpine re-base help, [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few. Check out all the [amazing contributors](https://github.com/jokob-sk/NetAlertX/graphs/contributors). +> [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) (the original creator of PiAlert), [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more), [Macleykun](https://github.com/Macleykun) (Help with Dockerfile clean-up), [vladaurosh](https://github.com/vladaurosh) for Alpine re-base help, [Final-Hawk](https://github.com/Final-Hawk) (Help with NTFY, styling and other fixes), [TeroRERO](https://github.com/terorero) (Spanish translations), [Data-Monkey](https://github.com/Data-Monkey), (Split-up of the python.py file and more), [cvc90](https://github.com/cvc90) (Spanish translation and various UI work) to name a few. Check out all the [amazing contributors](https://github.com/jokob-sk/NetAlertX/graphs/contributors). -### 🌍 Translations +### 🌍 Translations Proudly using [Weblate](https://hosted.weblate.org/projects/pialert/). Help out and suggest languages in the [online portal of Weblate](https://hosted.weblate.org/projects/pialert/core/). diff --git a/docs/DEBUG_TIPS.md b/docs/DEBUG_TIPS.md index a5c63fbd..4362f32c 100755 --- a/docs/DEBUG_TIPS.md +++ b/docs/DEBUG_TIPS.md @@ -1,30 +1,35 @@ # Debugging and troubleshooting -Please follow tips 1 - 4 to get a more detailed error. +Please follow tips 1 - 4 to get a more detailed error. -## 1. More Logging +## 1. More Logging When debugging an issue always set the highest log level: `LOG_LEVEL='trace'` -## 2. Surfacing errors when container restarts +## 2. Surfacing errors when container restarts Start the container via the **terminal** with a command similar to this one: ```bash -docker run --rm --network=host \ - -v /local_data_dir/netalertx/config:/data/config \ - -v /local_data_dir/netalertx/db:/data/db \ - -v /etc/localtime:/etc/localtime \ +docker run \ + --network=host \ + --restart unless-stopped \ + -v /local_data_dir/config:/data/config \ + -v /local_data_dir/db:/data/db \ + -v /etc/localtime:/etc/localtime:ro \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ -e PORT=20211 \ + -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \ ghcr.io/jokob-sk/netalertx:latest ``` -> ⚠ Please note, don't use the `-d` parameter so you see the error when the container crashes. Use this error in your issue description. +> [!NOTE] +> ⚠ The most important part is NOT to use the `-d` parameter so you see the error when the container crashes. Use this error in your issue description. -## 3. Check the _dev image and open issues +## 3. Check the _dev image and open issues If possible, check if your issue got fixed in the `_dev` image before opening a new issue. The container is: @@ -34,7 +39,7 @@ If possible, check if your issue got fixed in the `_dev` image before opening a Please also search [open issues](https://github.com/jokob-sk/NetAlertX/issues). -## 4. Disable restart behavior +## 4. Disable restart behavior To prevent a Docker container from automatically restarting in a Docker Compose file, specify the restart policy as `no`: @@ -48,9 +53,22 @@ services: # Other service configurations... ``` -## 5. Sharing application state +## 5. TMP mount directories to rule host out permission issues -Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong. +Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. + +```bash +docker run --rm --network=host \ + -v /etc/localtime:/etc/localtime:ro \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ + -e PORT=20211 \ + ghcr.io/jokob-sk/netalertx:latest +``` + + +## 6. Sharing application state + +Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong. 1. Please set `LOG_LEVEL` to `trace` (Disable it once you have the info as this produces big log files). 2. Wait for the issue to occur. @@ -61,4 +79,4 @@ Sometimes specific log sections are needed to debug issues. The Devices and Curr ## Common issues -See [Common issues](./COMMON_ISSUES.md) for details. +See [Common issues](./COMMON_ISSUES.md) for details. diff --git a/docs/DOCKER_INSTALLATION.md b/docs/DOCKER_INSTALLATION.md index 2acdb571..cd4988f3 100644 --- a/docs/DOCKER_INSTALLATION.md +++ b/docs/DOCKER_INSTALLATION.md @@ -7,7 +7,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) -|----------------------| ----------------------| ----------------------| ----------------------| ----------------------| +|----------------------| ----------------------| ----------------------| ----------------------| ----------------------| @@ -16,9 +16,9 @@ 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://github.com/jokob-sk/NetAlertX/blob/main/docs/HW_INSTALL.md) method available. -## 📕 Basic Usage +## 📕 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. @@ -28,7 +28,7 @@ docker run -d --rm --network=host \ -v /local_data_dir/config:/data/config \ -v /local_data_dir/db:/data/db \ -v /etc/localtime:/etc/localtime \ - --mount type=tmpfs,target=/tmp/api \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ -e PORT=20211 \ -e APP_CONF_OVERRIDE={"GRAPHQL_PORT":"20214"} \ ghcr.io/jokob-sk/netalertx:latest @@ -58,49 +58,49 @@ 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://github.com/jokob-sk/NetAlertX/blob/main/docs/BACKUPS.md). | Required | Path | Description | -| :------------- | :------------- | :-------------| -| ✅ | `:/data/config` | Folder which will contain the `app.conf` & `devices.csv` ([read about devices.csv](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)) files | -| ✅ | `:/data/db` | Folder which will contain the `app.db` database file | -| ✅ | `/etc/localtime:/etc/localtime:ro` | Ensuring the timezone is teh same as on teh 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//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). | +| :------------- | :------------- | :-------------| +| ✅ | `:/data/config` | Folder which will contain the `app.conf` & `devices.csv` ([read about devices.csv](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)) files | +| ✅ | `:/data/db` | Folder which will contain the `app.db` database file | +| ✅ | `/etc/localtime:/etc/localtime:ro` | Ensuring the timezone is teh same as on teh 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//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). | > Use separate `db` and `config` directories, do not nest them. ### Initial setup - If unavailable, the app generates a default `app.conf` and `app.db` file on the first run. -- The preferred way is to manage the configuration via the Settings section in the UI, if UI is inaccessible you can modify [app.conf](https://github.com/jokob-sk/NetAlertX/tree/main/back) in the `/data/config/` folder directly +- The preferred way is to manage the configuration via the Settings section in the UI, if UI is inaccessible you can modify [app.conf](https://github.com/jokob-sk/NetAlertX/tree/main/back) in the `/data/config/` folder directly #### 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://github.com/jokob-sk/NetAlertX/blob/main/docs/SUBNETS.md) 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://github.com/jokob-sk/NetAlertX/blob/main/docs/PIHOLE_GUIDE.md) 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). #### 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://github.com/jokob-sk/NetAlertX/blob/main/docs/COMMUNITY_GUIDES.md) in Chinese, Korean, German, or French. + +> Please note these might be outdated. Rely on official documentation first. -> 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). +- 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). -## 💙 Support me +## 💙 Support me -| [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) | [![Patreon](https://i.imgur.com/MuYsrq1.png)](https://www.patreon.com/user?u=84385063) | -| --- | --- | --- | +| [![GitHub](https://i.imgur.com/emsRCPh.png)](https://github.com/sponsors/jokob-sk) | [![Buy Me A Coffee](https://i.imgur.com/pIM6YXL.png)](https://www.buymeacoffee.com/jokobsk) | [![Patreon](https://i.imgur.com/MuYsrq1.png)](https://www.patreon.com/user?u=84385063) | +| --- | --- | --- | - Bitcoin: `1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM` - Ethereum: `0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7` diff --git a/docs/DOCKER_PORTAINER.md b/docs/DOCKER_PORTAINER.md index ba97dcd6..6fb13ccc 100755 --- a/docs/DOCKER_PORTAINER.md +++ b/docs/DOCKER_PORTAINER.md @@ -34,30 +34,26 @@ Copy and paste the following YAML into the **Web editor**: services: netalertx: container_name: netalertx - # Use this line for stable release - image: "ghcr.io/jokob-sk/netalertx:latest" - + image: "ghcr.io/jokob-sk/netalertx:latest" # Or, use this for the latest development build - # image: "ghcr.io/jokob-sk/netalertx-dev:latest" - + # image: "ghcr.io/jokob-sk/netalertx-dev:latest" network_mode: "host" restart: unless-stopped - + cap_drop: # Drop all capabilities for enhanced security + - ALL + cap_add: # Re-add necessary capabilities + - NET_RAW + - NET_ADMIN + - NET_BIND_SERVICE volumes: - ${APP_FOLDER}/netalertx/config:/data/config - ${APP_FOLDER}/netalertx/db:/data/db - # Optional: logs (useful for debugging setup issues, comment out for performance) - - ${APP_FOLDER}/netalertx/log:/tmp/log - - # API storage options: - # (Option 1) tmpfs (default, best performance) - - type: tmpfs - target: /tmp/api - - # (Option 2) bind mount (useful for debugging) - # - ${APP_FOLDER}/netalertx/api:/tmp/api - + # to sync with system time + - /etc/localtime:/etc/localtime:ro + tmpfs: + # All writable runtime state resides under /tmp; comment out to persist logs between restarts + - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime" environment: - PORT=${PORT} - APP_CONF_OVERRIDE=${APP_CONF_OVERRIDE} @@ -78,7 +74,7 @@ In the **Environment variables** section of Portainer, add the following: ## 5. Ensure permissions > [!TIP] -> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir @@ -104,4 +100,4 @@ http://:22022 * Check logs via Portainer → **Containers** → `netalertx` → **Logs**. * Logs are stored under `${APP_FOLDER}/netalertx/log` if you enabled that volume. -Once the application is running, configure it by reading the [initial setup](INITIAL_SETUP.md) guide, or [troubleshoot common issues](COMMON_ISSUES.md). +Once the application is running, configure it by reading the [initial setup](INITIAL_SETUP.md) guide, or [troubleshoot common issues](COMMON_ISSUES.md). diff --git a/docs/DOCKER_SWARM.md b/docs/DOCKER_SWARM.md index 89ab6381..f1af830c 100755 --- a/docs/DOCKER_SWARM.md +++ b/docs/DOCKER_SWARM.md @@ -41,15 +41,7 @@ Use the following Compose snippet to deploy NetAlertX with a **static LAN IP** a services: netalertx: image: ghcr.io/jokob-sk/netalertx:latest - ports: - - 20211:20211 - volumes: - - /mnt/YOUR_SERVER/netalertx/config:/data/config:rw - - /mnt/YOUR_SERVER/netalertx/db:/netalertx/data/db:rw - - /mnt/YOUR_SERVER/netalertx/logs:/netalertx/tmp/log:rw - - /etc/localtime:/etc/localtime:ro - environment: - - PORT=20211 +... networks: swarm-ipvlan: ipv4_address: 192.168.1.240 # ⚠ Choose a free IP from your LAN diff --git a/docs/FILE_PERMISSIONS.md b/docs/FILE_PERMISSIONS.md index 7e0e9984..d634e516 100755 --- a/docs/FILE_PERMISSIONS.md +++ b/docs/FILE_PERMISSIONS.md @@ -37,6 +37,7 @@ Sometimes, permission issues arise if your existing host directories were create docker run -it --rm --name netalertx --user "0" \ -v /local_data_dir/config:/data/config \ -v /local_data_dir/db:/data/db \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ ghcr.io/jokob-sk/netalertx:latest ``` @@ -47,7 +48,7 @@ docker run -it --rm --name netalertx --user "0" \ > The container startup script detects `root` and runs `chown -R 20211:20211` on all volumes, fixing ownership for the secure `netalertx` user. > [!TIP] -> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir @@ -59,22 +60,22 @@ docker run -it --rm --name netalertx --user "0" \ ```yaml services: - netalertx: - container_name: netalertx - image: "ghcr.io/jokob-sk/netalertx" - network_mode: "host" + netalertx: + container_name: netalertx + image: "ghcr.io/jokob-sk/netalertx" + network_mode: "host" cap_drop: # Drop all capabilities for enhanced security - - ALL + - ALL cap_add: # Add only the necessary capabilities - NET_ADMIN # Required for ARP scanning - NET_RAW # Required for raw socket operations - NET_BIND_SERVICE # Required to bind to privileged ports (nbtscan) restart: unless-stopped volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db - - /etc/localtime:/etc/localtime - environment: + - /local_data_dir/config:/data/config + - /local_data_dir/db:/data/db + - /etc/localtime:/etc/localtime + environment: - PORT=20211 tmpfs: - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime" diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index b71c2c10..fb112405 100755 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,8 +1,8 @@ -# Migration +# Migration > [!WARNING] -> ⚠ **Important:** The documentation has been recently updated and some instructions may have changed. -> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container. +> ⚠ **Important:** The documentation has been recently updated and some instructions may have changed. +> If you are using the currently live production image, please follow the instructions on [Docker Hub](https://hub.docker.com/r/jokobsk/netalertx) for building and running the container. > These docs reflect the latest development version and may differ from the production image. @@ -13,13 +13,13 @@ When upgrading from older versions of NetAlertX (or PiAlert by jokob-sk), follow ## Migration scenarios -- You are running PiAlert (by jokob-sk) +- You are running PiAlert (by jokob-sk) → [Read the 1.1 Migration from PiAlert to NetAlertX `v25.5.24`](#11-migration-from-pialert-to-netalertx-v25524) -- You are running NetAlertX (by jokob-sk) `25.5.24` or older +- You are running NetAlertX (by jokob-sk) `25.5.24` or older → [Read the 1.2 Migration from NetAlertX `v25.5.24`](#12-migration-from-netalertx-v25524) -- You are running NetAlertX (by jokob-sk) (`v25.6.7` to `v25.10.1`) +- You are running NetAlertX (by jokob-sk) (`v25.6.7` to `v25.10.1`) → [Read the 1.3 Migration from NetAlertX `v25.10.1`](#13-migration-from-netalertx-v25101) @@ -30,40 +30,40 @@ You can migrate data manually, for example by exporting and importing devices us ### 1.1 Migration from PiAlert to NetAlertX `v25.5.24` -#### STEPS: +#### STEPS: The application will automatically migrate the database, configuration, and all device information. A banner message will appear at the top of the web UI reminding you to update your Docker mount points. -1. Stop the container -2. [Back up your setup](./BACKUPS.md) -3. Update the Docker file mount locations in your `docker-compose.yml` or docker run command (See below **New Docker mount locations**). +1. Stop the container +2. [Back up your setup](./BACKUPS.md) +3. Update the Docker file mount locations in your `docker-compose.yml` or docker run command (See below **New Docker mount locations**). 4. Rename the DB and conf files to `app.db` and `app.conf` and place them in the appropriate location. 5. Start the container -> [!TIP] -> If you have trouble accessing past backups, config or database files you can copy them into the newly mapped directories, for example by running this command in the container: `cp -r /data/config /home/pi/pialert/config/old_backup_files`. This should create a folder in the `config` directory called `old_backup_files` containing all the files in that location. Another approach is to map the old location and the new one at the same time to copy things over. +> [!TIP] +> If you have trouble accessing past backups, config or database files you can copy them into the newly mapped directories, for example by running this command in the container: `cp -r /data/config /home/pi/pialert/config/old_backup_files`. This should create a folder in the `config` directory called `old_backup_files` containing all the files in that location. Another approach is to map the old location and the new one at the same time to copy things over. #### New Docker mount locations The internal application path in the container has changed from `/home/pi/pialert` to `/app`. Update your volume mounts as follows: - | Old mount point | New mount point | - |----------------------|---------------| + | Old mount point | New mount point | + |----------------------|---------------| | `/home/pi/pialert/config` | `/data/config` | | `/home/pi/pialert/db` | `/data/db` | If you were mounting files directly, please note the file names have changed: - | Old file name | New file name | - |----------------------|---------------| + | Old file name | New file name | + |----------------------|---------------| | `pialert.conf` | `app.conf` | | `pialert.db` | `app.db` | -> [!NOTE] +> [!NOTE] > The application automatically creates symlinks from the old database and config locations to the new ones, so data loss should not occur. Read the [backup strategies](./BACKUPS.md) guide to backup your setup. @@ -80,17 +80,17 @@ services: pialert: container_name: pialert # use the below line if you want to test the latest dev image - # image: "ghcr.io/jokob-sk/netalertx-dev:latest" - image: "jokobsk/pialert:latest" - network_mode: "host" + # image: "ghcr.io/jokob-sk/netalertx-dev:latest" + image: "jokobsk/pialert:latest" + network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config:/home/pi/pialert/config - - /local_data_dir/db:/home/pi/pialert/db + - /local_data_dir/config:/home/pi/pialert/config + - /local_data_dir/db:/home/pi/pialert/db # (optional) useful for debugging if you have issues setting up the container - /local_data_dir/logs:/home/pi/pialert/front/log environment: - - TZ=Europe/Berlin + - TZ=Europe/Berlin - PORT=20211 ``` @@ -98,26 +98,26 @@ services: ```yaml services: - netalertx: # 🆕 This has changed - container_name: netalertx # 🆕 This has changed - image: "ghcr.io/jokob-sk/netalertx:25.5.24" # 🆕 This has changed - network_mode: "host" + netalertx: # 🆕 This has changed + container_name: netalertx # 🆕 This has changed + image: "ghcr.io/jokob-sk/netalertx:25.5.24" # 🆕 This has changed + network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config:/data/config # 🆕 This has changed - - /local_data_dir/db:/data/db # 🆕 This has changed + - /local_data_dir/config:/data/config # 🆕 This has changed + - /local_data_dir/db:/data/db # 🆕 This has changed # (optional) useful for debugging if you have issues setting up the container - - /local_data_dir/logs:/tmp/log # 🆕 This has changed + - /local_data_dir/logs:/tmp/log # 🆕 This has changed environment: - - TZ=Europe/Berlin + - TZ=Europe/Berlin - PORT=20211 ``` ##### Example 2: Mapping files -> [!NOTE] -> The recommendation is to map folders as in Example 1, map files directly only when needed. +> [!NOTE] +> The recommendation is to map folders as in Example 1, map files directly only when needed. ###### Old docker-compose.yml @@ -126,17 +126,17 @@ services: pialert: container_name: pialert # use the below line if you want to test the latest dev image - # image: "ghcr.io/jokob-sk/netalertx-dev:latest" - image: "jokobsk/pialert:latest" - network_mode: "host" + # image: "ghcr.io/jokob-sk/netalertx-dev:latest" + image: "jokobsk/pialert:latest" + network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config/pialert.conf:/home/pi/pialert/config/pialert.conf - - /local_data_dir/db/pialert.db:/home/pi/pialert/db/pialert.db + - /local_data_dir/config/pialert.conf:/home/pi/pialert/config/pialert.conf + - /local_data_dir/db/pialert.db:/home/pi/pialert/db/pialert.db # (optional) useful for debugging if you have issues setting up the container - /local_data_dir/logs:/home/pi/pialert/front/log environment: - - TZ=Europe/Berlin + - TZ=Europe/Berlin - PORT=20211 ``` @@ -144,18 +144,18 @@ services: ```yaml services: - netalertx: # 🆕 This has changed - container_name: netalertx # 🆕 This has changed - image: "ghcr.io/jokob-sk/netalertx:25.5.24" # 🆕 This has changed - network_mode: "host" + netalertx: # 🆕 This has changed + container_name: netalertx # 🆕 This has changed + image: "ghcr.io/jokob-sk/netalertx:25.5.24" # 🆕 This has changed + network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config/app.conf:/data/config/app.conf # 🆕 This has changed - - /local_data_dir/db/app.db:/data/db/app.db # 🆕 This has changed + - /local_data_dir/config/app.conf:/data/config/app.conf # 🆕 This has changed + - /local_data_dir/db/app.db:/data/db/app.db # 🆕 This has changed # (optional) useful for debugging if you have issues setting up the container - - /local_data_dir/logs:/tmp/log # 🆕 This has changed + - /local_data_dir/logs:/tmp/log # 🆕 This has changed environment: - - TZ=Europe/Berlin + - TZ=Europe/Berlin - PORT=20211 ``` @@ -164,13 +164,13 @@ services: Versions before `v25.10.1` require an intermediate migration through `v25.5.24` to ensure database compatibility. Skipping this step may cause compatibility issues due to database schema changes introduced after `v25.5.24`. -#### STEPS: +#### STEPS: -1. Stop the container -2. [Back up your setup](./BACKUPS.md) +1. Stop the container +2. [Back up your setup](./BACKUPS.md) 3. Upgrade to `v25.5.24` by pinning the release version (See Examples below) 4. Start the container and verify everything works as expected. -5. Stop the container +5. Stop the container 6. Upgrade to `v25.10.1` by pinning the release version (See Examples below) 7. Start the container and verify everything works as expected. @@ -184,62 +184,62 @@ Examples of docker files with the tagged version. ```yaml services: - netalertx: - container_name: netalertx - image: "ghcr.io/jokob-sk/netalertx:25.5.24" # 🆕 This is important - network_mode: "host" + netalertx: + container_name: netalertx + image: "ghcr.io/jokob-sk/netalertx:25.5.24" # 🆕 This is important + network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db + - /local_data_dir/config:/data/config + - /local_data_dir/db:/data/db # (optional) useful for debugging if you have issues setting up the container - - /local_data_dir/logs:/tmp/log + - /local_data_dir/logs:/tmp/log environment: - - TZ=Europe/Berlin + - TZ=Europe/Berlin - PORT=20211 ``` ```yaml services: - netalertx: - container_name: netalertx - image: "ghcr.io/jokob-sk/netalertx:25.10.1" # 🆕 This is important - network_mode: "host" + netalertx: + container_name: netalertx + image: "ghcr.io/jokob-sk/netalertx:25.10.1" # 🆕 This is important + network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db + - /local_data_dir/config:/data/config + - /local_data_dir/db:/data/db # (optional) useful for debugging if you have issues setting up the container - - /local_data_dir/logs:/tmp/log + - /local_data_dir/logs:/tmp/log environment: - - TZ=Europe/Berlin + - TZ=Europe/Berlin - PORT=20211 ``` ### 1.3 Migration from NetAlertX `v25.10.1` -Starting from v25.10.1, the container uses a [more secure, read-only runtime environment](./SECURITY_FEATURES.md), which requires all writable paths (e.g., logs, API cache, temporary data) to be mounted as `tmpfs` or permanent writable volumes, with sufficient access [permissions](./FILE_PERMISSIONS.md). +Starting from v25.10.1, the container uses a [more secure, read-only runtime environment](./SECURITY_FEATURES.md), which requires all writable paths (e.g., logs, API cache, temporary data) to be mounted as `tmpfs` or permanent writable volumes, with sufficient access [permissions](./FILE_PERMISSIONS.md). -#### STEPS: +#### STEPS: -1. Stop the container -2. [Back up your setup](./BACKUPS.md) +1. Stop the container +2. [Back up your setup](./BACKUPS.md) 3. Upgrade to `v25.10.1` by pinning the release version (See the example below) ```yaml services: - netalertx: - container_name: netalertx - image: "ghcr.io/jokob-sk/netalertx:25.10.1" # 🆕 This is important - network_mode: "host" + netalertx: + container_name: netalertx + image: "ghcr.io/jokob-sk/netalertx:25.10.1" # 🆕 This is important + network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db + - /local_data_dir/config:/data/config + - /local_data_dir/db:/data/db # (optional) useful for debugging if you have issues setting up the container - - /local_data_dir/logs:/tmp/log + - /local_data_dir/logs:/tmp/log environment: - - TZ=Europe/Berlin + - TZ=Europe/Berlin - PORT=20211 ``` @@ -248,13 +248,14 @@ services: 6. Perform a one-off migration to the latest `netalertx` image and `20211` user: > [!NOTE] -> The example below assumes your `/config` and `/db` folders are stored in `local_data_dir`. +> The example below assumes your `/config` and `/db` folders are stored in `local_data_dir`. > Replace this path with your actual configuration directory. `netalertx` is the container name, which might differ from your setup. ```sh docker run -it --rm --name netalertx --user "0" \ -v /local_data_dir/config:/data/config \ -v /local_data_dir/db:/data/db \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ ghcr.io/jokob-sk/netalertx:latest ``` @@ -271,22 +272,22 @@ sudo chmod -R a+rwx /local_data_dir/ ```yaml services: - netalertx: - container_name: netalertx - image: "ghcr.io/jokob-sk/netalertx" # 🆕 This is important - network_mode: "host" + netalertx: + container_name: netalertx + image: "ghcr.io/jokob-sk/netalertx" # 🆕 This has changed + network_mode: "host" cap_drop: # 🆕 New line - ALL # 🆕 New line cap_add: # 🆕 New line - - NET_RAW # 🆕 New line + - NET_RAW # 🆕 New line - NET_ADMIN # 🆕 New line - - NET_BIND_SERVICE # 🆕 New line + - NET_BIND_SERVICE # 🆕 New line restart: unless-stopped volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db + - /local_data_dir/config:/data/config + - /local_data_dir/db:/data/db # (optional) useful for debugging if you have issues setting up the container - #- /local_data_dir/logs:/tmp/log + #- /local_data_dir/logs:/tmp/log # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured - /etc/localtime:/etc/localtime:ro # 🆕 New line environment: diff --git a/docs/PERFORMANCE.md b/docs/PERFORMANCE.md index 0434bbcf..b8589141 100755 --- a/docs/PERFORMANCE.md +++ b/docs/PERFORMANCE.md @@ -1,47 +1,50 @@ # Performance Optimization Guide -There are several ways to improve the application's performance. The application has been tested on a range of devices, from a Raspberry Pi 4 to NAS and NUC systems. If you are running the application on a lower-end device, carefully fine-tune the performance settings to ensure an optimal user experience. +There are several ways to improve the application's performance. The application has been tested on a range of devices, from Raspberry Pi 4 units to NAS and NUC systems. If you are running the application on a lower-end device, fine-tuning the performance settings can significantly improve the user experience. ## Common Causes of Slowness Performance issues are usually caused by: -- **Incorrect settings** – The app may restart unexpectedly. Check `app.log` under **Maintenance → Logs** for details. -- **Too many background processes** – Disable unnecessary scanners. -- **Long scan durations** – Limit the number of scanned devices. -- **Excessive disk operations** – Optimize scanning and logging settings. -- **Failed maintenance plugins** – Ensure maintenance tasks are running properly. +* **Incorrect settings** – The app may restart unexpectedly. Check `app.log` under **Maintenance → Logs** for details. +* **Too many background processes** – Disable unnecessary scanners. +* **Long scan durations** – Limit the number of scanned devices. +* **Excessive disk operations** – Optimize scanning and logging settings. +* **Maintenance plugin failures** – If cleanup tasks fail, performance can degrade over time. -The application performs regular maintenance and database cleanup. If these tasks fail, performance may degrade. +The application performs regular maintenance and database cleanup. If these tasks are failing, you will see slowdowns. ### Database and Log File Size -A large database or oversized log files can slow down performance. You can check database and table sizes on the **Maintenance** page. +A large database or oversized log files can impact performance. You can check database and table sizes on the **Maintenance** page. ![DB size check](./img/PERFORMANCE/db_size_check.png) > [!NOTE] -> - For **~100 devices**, the database should be around **50MB**. -> - No table should exceed **10,000 rows** in a healthy system. -> - These numbers vary based on network activity and settings. +> +> * For **~100 devices**, the database should be around **50 MB**. +> * No table should exceed **10,000 rows** in a healthy system. +> * Actual values vary based on network activity and plugin settings. --- ## Maintenance Plugins -Two plugins help maintain the application’s performance: +Two plugins help maintain the system’s performance: ### **1. Database Cleanup (DBCLNP)** -- Responsible for database maintenance. -- Check settings in the [DB Cleanup Plugin Docs](/front/plugins/db_cleanup/README.md). -- Ensure it’s not failing by checking logs. -- Adjust the schedule (`DBCLNP_RUN_SCHD`) and timeout (`DBCLNP_RUN_TIMEOUT`) if needed. + +* Handles database maintenance and cleanup. +* See the [DB Cleanup Plugin Docs](/front/plugins/db_cleanup/README.md). +* Ensure it’s not failing by checking logs. +* Adjust the schedule (`DBCLNP_RUN_SCHD`) and timeout (`DBCLNP_RUN_TIMEOUT`) if necessary. ### **2. Maintenance (MAINT)** -- Handles log cleanup and other maintenance tasks. -- Check settings in the [Maintenance Plugin Docs](/front/plugins/maintenance/README.md). -- Ensure it’s running correctly by checking logs. -- Adjust the schedule (`MAINT_RUN_SCHD`) and timeout (`MAINT_RUN_TIMEOUT`) if needed. + +* Cleans logs and performs general maintenance tasks. +* See the [Maintenance Plugin Docs](/front/plugins/maintenance/README.md). +* Verify proper operation via logs. +* Adjust the schedule (`MAINT_RUN_SCHD`) and timeout (`MAINT_RUN_TIMEOUT`) if needed. --- @@ -50,48 +53,56 @@ Two plugins help maintain the application’s performance: Frequent scans increase resource usage, network traffic, and database read/write cycles. ### **Optimizations** -- **Increase scan intervals** (`_RUN_SCHD`) on busy networks or low-end hardware. -- **Extend scan timeouts** (`_RUN_TIMEOUT`) to prevent failures. -- **Reduce the subnet size** – e.g., from `/16` to `/24` to lower scan loads. -Some plugins have additional options to limit the number of scanned devices. If certain plugins take too long to complete, check if you can optimize scan times by selecting a scan range. +* **Increase scan intervals** (`_RUN_SCHD`) on busy networks or low-end hardware. +* **Increase timeouts** (`_RUN_TIMEOUT`) to avoid plugin failures. +* **Reduce subnet size** – e.g., use `/24` instead of `/16` to reduce scan load. -For example, the **ICMP plugin** allows you to specify a regular expression to scan only IPs that match a specific pattern. +Some plugins also include options to limit which devices are scanned. If certain plugins consistently run long, consider narrowing their scope. + +For example, the **ICMP plugin** allows scanning only IPs that match a specific regular expression. --- ## Storing Temporary Files in Memory -On systems with slower I/O speeds, you can optimize performance by storing temporary files in memory. This primarily applies to the API directory (default: `/tmp/api`, configurable via `NETALERTX_API`) and `/tmp/log` folders. +On devices with slower I/O, you can improve performance by storing temporary files (and optionally the database) in memory using `tmpfs`. -Using `tmpfs` reduces disk writes and improves performance. However, it should be **disabled** if persistent logs or API data storage are required. +> [!WARNING] +> Storing the **database** in `tmpfs` is generally discouraged. Use this only if device data and historical records are not required to persist. If needed, you can pair this setup with the `SYNC` plugin to store important persistent data on another node. See the [Plugins docs](./PLUGINS.md) for details. -Below is an optimized `docker-compose.yml` snippet: +Using `tmpfs` reduces disk writes and speeds up I/O, but **all data stored in memory will be lost on restart**. +Below is an optimized `docker-compose.yml` snippet using non-persistent logs, API data, and DB: ```yaml -version: "3" services: netalertx: container_name: netalertx - # Uncomment the line below to test the latest dev image + # Use this line for the stable release + image: "ghcr.io/jokob-sk/netalertx:latest" + # Or use this line for the latest development build # image: "ghcr.io/jokob-sk/netalertx-dev:latest" - image: "ghcr.io/jokob-sk/netalertx:latest" - network_mode: "host" + network_mode: "host" restart: unless-stopped - volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db - # (Optional) Useful for debugging setup issues - - /local_data_dir/logs:/tmp/log - # (API: OPTION 1) Store temporary files in memory (recommended for performance) - - type: tmpfs # ◀ 🔺 - target: /tmp/api # ◀ 🔺 - # (API: OPTION 2) Store API data on disk (useful for debugging) - # - /local_data_dir/api:/tmp/api - # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured - - /etc/localtime:/etc/localtime:ro - environment: - - PORT=20211 + cap_drop: # Drop all capabilities for enhanced security + - ALL + cap_add: # Re-add necessary capabilities + - NET_RAW + - NET_ADMIN + - NET_BIND_SERVICE + + volumes: + - ${APP_FOLDER}/netalertx/config:/data/config + - /etc/localtime:/etc/localtime:ro + + tmpfs: + # All writable runtime state resides under /tmp; comment out to persist logs between restarts + - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime" + - "/data/db:uid=20211,gid=20211,mode=1700" # ⚠ You will lose historical data on restart + + environment: + - PORT=${PORT} + - APP_CONF_OVERRIDE=${APP_CONF_OVERRIDE} ``` diff --git a/docs/REVERSE_DNS.md b/docs/REVERSE_DNS.md index 4576c18d..69e6a2bc 100755 --- a/docs/REVERSE_DNS.md +++ b/docs/REVERSE_DNS.md @@ -2,21 +2,21 @@ If you are running a DNS server, such as **AdGuard**, set up **Private reverse DNS servers** for a better name resolution on your network. Enabling this setting will enable NetAlertX to execute dig and nslookup commands to automatically resolve device names based on their IP addresses. -> [!TIP] -> Before proceeding, ensure that [name resolution plugins](/local_data_dir/NAME_RESOLUTION.md) are enabled. -> You can customize how names are cleaned using the `NEWDEV_NAME_CLEANUP_REGEX` setting. +> [!TIP] +> Before proceeding, ensure that [name resolution plugins](/local_data_dir/NAME_RESOLUTION.md) are enabled. +> You can customize how names are cleaned using the `NEWDEV_NAME_CLEANUP_REGEX` setting. > To auto-update Fully Qualified Domain Names (FQDN), enable the `REFRESH_FQDN` setting. > Example 1: Reverse DNS `disabled` -> +> > ``` > jokob@Synology-NAS:/$ nslookup 192.168.1.58 > ** server can't find 58.1.168.192.in-addr.arpa: NXDOMAIN > ``` > Example 2: Reverse DNS `enabled` -> +> > ``` > jokob@Synology-NAS:/$ nslookup 192.168.1.58 > 45.1.168.192.in-addr.arpa name = jokob-NUC.localdomain. @@ -33,23 +33,14 @@ If you are running a DNS server, such as **AdGuard**, set up **Private reverse D ### Specifying the DNS in the container -You can specify the DNS server in the docker-compose to improve name resolution on your network. +You can specify the DNS server in the docker-compose to improve name resolution on your network. ```yaml services: netalertx: container_name: netalertx image: "ghcr.io/jokob-sk/netalertx:latest" - restart: unless-stopped - volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db - # - /local_data_dir/log:/tmp/log - # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured - - /etc/localtime:/etc/localtime:ro - environment: - - PORT=20211 - network_mode: host +... dns: # specifying the DNS servers used for the container - 10.8.0.1 - 10.8.0.17 @@ -57,7 +48,7 @@ services: ### Using a custom resolv.conf file -You can configure a custom **/etc/resolv.conf** file in **docker-compose.yml** and set the nameserver to your LAN DNS server (e.g.: Pi-Hole). See the relevant [resolv.conf man](https://www.man7.org/linux/man-pages/man5/resolv.conf.5.html) entry for details. +You can configure a custom **/etc/resolv.conf** file in **docker-compose.yml** and set the nameserver to your LAN DNS server (e.g.: Pi-Hole). See the relevant [resolv.conf man](https://www.man7.org/linux/man-pages/man5/resolv.conf.5.html) entry for details. #### docker-compose.yml: @@ -66,18 +57,10 @@ version: "3" services: netalertx: container_name: netalertx - image: "ghcr.io/jokob-sk/netalertx:latest" - restart: unless-stopped volumes: - - /local_data_dir/config/app.conf:/data/config/app.conf - - /local_data_dir/db:/data/db - - /local_data_dir/log:/tmp/log +... - /local_data_dir/config/resolv.conf:/etc/resolv.conf # ⚠ Mapping the /resolv.conf file for better name resolution - # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured - - /etc/localtime:/etc/localtime:ro - environment: - - PORT=20211 - network_mode: host +... ``` #### /local_data_dir/config/resolv.conf: diff --git a/docs/REVERSE_PROXY.md b/docs/REVERSE_PROXY.md index 4723ec93..ee12c11d 100755 --- a/docs/REVERSE_PROXY.md +++ b/docs/REVERSE_PROXY.md @@ -2,9 +2,9 @@ > Submitted by amazing [cvc90](https://github.com/cvc90) 🙏 -> [!NOTE] +> [!NOTE] > There are various NGINX config files for NetAlertX, some for the bare-metal install, currently Debian 12 and Ubuntu 24 (`netalertx.conf`), and one for the docker container (`netalertx.template.conf`). -> +> > The first one you can find in the respective bare metal installer folder `/app/install/\/netalertx.conf`. > The docker one can be found in the [install](https://github.com/jokob-sk/NetAlertX/tree/main/install) folder. Map, or use, the one appropriate for your setup. @@ -17,14 +17,14 @@ 2. In this file, paste the following code: ``` - server { - listen 80; - server_name netalertx; - proxy_preserve_host on; - proxy_pass http://localhost:20211/; - proxy_pass_reverse http://localhost:20211/; + server { + listen 80; + server_name netalertx; + proxy_preserve_host on; + proxy_pass http://localhost:20211/; + proxy_pass_reverse http://localhost:20211/; } -``` +``` 3. Activate the new website by running the following command: @@ -43,18 +43,18 @@ 2. In this file, paste the following code: ``` - server { - listen 80; - server_name netalertx; - proxy_preserve_host on; + server { + listen 80; + server_name netalertx; + proxy_preserve_host on; location ^~ /netalertx/ { proxy_pass http://localhost:20211/; - proxy_pass_reverse http://localhost:20211/; + proxy_pass_reverse http://localhost:20211/; proxy_redirect ~^/(.*)$ /netalertx/$1; - rewrite ^/netalertx/?(.*)$ /$1 break; + rewrite ^/netalertx/?(.*)$ /$1 break; } } -``` +``` 3. Check your config with `nginx -t`. If there are any issues, it will tell you. @@ -73,13 +73,13 @@ 2. In this file, paste the following code: ``` - server { - listen 80; - server_name netalertx; - proxy_preserve_host on; + server { + listen 80; + server_name netalertx; + proxy_preserve_host on; location ^~ /netalertx/ { proxy_pass http://localhost:20211/; - proxy_pass_reverse http://localhost:20211/; + proxy_pass_reverse http://localhost:20211/; proxy_redirect ~^/(.*)$ /netalertx/$1; rewrite ^/netalertx/?(.*)$ /$1 break; sub_filter_once off; @@ -89,13 +89,13 @@ sub_filter '(?>$host)/js' '/netalertx/js'; sub_filter '/img' '/netalertx/img'; sub_filter '/lib' '/netalertx/lib'; - sub_filter '/php' '/netalertx/php'; + sub_filter '/php' '/netalertx/php'; } } -``` +``` 3. Check your config with `nginx -t`. If there are any issues, it will tell you. - + 4. Activate the new website by running the following command: `nginx -s reload` or `systemctl restart nginx` @@ -111,17 +111,17 @@ 2. In this file, paste the following code: ``` - server { - listen 443; - server_name netalertx; + server { + listen 443; + server_name netalertx; SSLEngine On; SSLCertificateFile /etc/ssl/certs/netalertx.pem; SSLCertificateKeyFile /etc/ssl/private/netalertx.key; - proxy_preserve_host on; - proxy_pass http://localhost:20211/; - proxy_pass_reverse http://localhost:20211/; + proxy_preserve_host on; + proxy_pass http://localhost:20211/; + proxy_pass_reverse http://localhost:20211/; } -``` +``` 3. Check your config with `nginx -t`. If there are any issues, it will tell you. @@ -140,23 +140,23 @@ 2. In this file, paste the following code: ``` - server { - listen 443; - server_name netalertx; + server { + listen 443; + server_name netalertx; SSLEngine On; SSLCertificateFile /etc/ssl/certs/netalertx.pem; SSLCertificateKeyFile /etc/ssl/private/netalertx.key; location ^~ /netalertx/ { proxy_pass http://localhost:20211/; - proxy_pass_reverse http://localhost:20211/; + proxy_pass_reverse http://localhost:20211/; proxy_redirect ~^/(.*)$ /netalertx/$1; - rewrite ^/netalertx/?(.*)$ /$1 break; + rewrite ^/netalertx/?(.*)$ /$1 break; } } -``` +``` 3. Check your config with `nginx -t`. If there are any issues, it will tell you. - + 4. Activate the new website by running the following command: `nginx -s reload` or `systemctl restart nginx` @@ -172,15 +172,15 @@ 2. In this file, paste the following code: ``` - server { - listen 443; - server_name netalertx; + server { + listen 443; + server_name netalertx; SSLEngine On; SSLCertificateFile /etc/ssl/certs/netalertx.pem; SSLCertificateKeyFile /etc/ssl/private/netalertx.key; location ^~ /netalertx/ { proxy_pass http://localhost:20211/; - proxy_pass_reverse http://localhost:20211/; + proxy_pass_reverse http://localhost:20211/; proxy_redirect ~^/(.*)$ /netalertx/$1; rewrite ^/netalertx/?(.*)$ /$1 break; sub_filter_once off; @@ -190,13 +190,13 @@ sub_filter '(?>$host)/js' '/netalertx/js'; sub_filter '/img' '/netalertx/img'; sub_filter '/lib' '/netalertx/lib'; - sub_filter '/php' '/netalertx/php'; + sub_filter '/php' '/netalertx/php'; } } -``` +``` 3. Check your config with `nginx -t`. If there are any issues, it will tell you. - + 4. Activate the new website by running the following command: `nginx -s reload` or `systemctl restart nginx` @@ -218,10 +218,10 @@ ProxyPass / http://localhost:20211/ ProxyPassReverse / http://localhost:20211/ -``` +``` 3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you. - + 4. Activate the new website by running the following command: `a2ensite netalertx` or `service apache2 reload` @@ -245,10 +245,10 @@ ProxyPassReverse / http://localhost:20211/ } -``` +``` 3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you. - + 4. Activate the new website by running the following command: `a2ensite netalertx` or `service apache2 reload` @@ -273,10 +273,10 @@ ProxyPass / http://localhost:20211/ ProxyPassReverse / http://localhost:20211/ -``` +``` 3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you. - + 4. Activate the new website by running the following command: `a2ensite netalertx` or `service apache2 reload` @@ -290,11 +290,11 @@ 1. On your Apache server, create a new file called /etc/apache2/sites-available/netalertx.conf. 2. In this file, paste the following code: - + ``` - + ServerName netalertx - SSLEngine On + SSLEngine On SSLCertificateFile /etc/ssl/certs/netalertx.pem SSLCertificateKeyFile /etc/ssl/private/netalertx.key location ^~ /netalertx/ { @@ -303,10 +303,10 @@ ProxyPassReverse / http://localhost:20211/ } -``` +``` 3. Check your config with `httpd -t` (or `apache2ctl -t` on Debian/Ubuntu). If there are any issues, it will tell you. - + 4. Activate the new website by running the following command: `a2ensite netalertx` or `service apache2 reload` @@ -381,7 +381,7 @@ location ^~ /netalertx/ { > Submitted by [Isegrimm](https://github.com/Isegrimm) 🙏 (based on this [discussion](https://github.com/jokob-sk/NetAlertX/discussions/449#discussioncomment-7281442)) -Assuming the user already has a working Traefik setup, this is what's needed to make NetAlertX work at a URL like www.domain.com/netalertx/. +Assuming the user already has a working Traefik setup, this is what's needed to make NetAlertX work at a URL like www.domain.com/netalertx/. Note: Everything in these configs assumes '**www.domain.com**' as your domainname and '**section31**' as an arbitrary name for your certificate setup. You will have to substitute these with your own. @@ -496,14 +496,9 @@ server { Mapping the updated file (on the local filesystem at `/appl/docker/netalertx/default`) into the docker container: -```bash -docker run -d --rm --network=host \ - --name=netalertx \ - -v /appl/docker/netalertx/config:/data/config \ - -v /appl/docker/netalertx/db:/data/db \ - -v /etc/localtime:/etc/localtime \ - -v /appl/docker/netalertx/default:/etc/nginx/sites-available/default \ - -e PORT=20211 \ - ghcr.io/jokob-sk/netalertx:latest - +```yaml +... + volumes: + - /appl/docker/netalertx/default:/etc/nginx/sites-available/default +... ``` diff --git a/docs/SYNOLOGY_GUIDE.md b/docs/SYNOLOGY_GUIDE.md index 8a8bdb96..dd6dec6d 100755 --- a/docs/SYNOLOGY_GUIDE.md +++ b/docs/SYNOLOGY_GUIDE.md @@ -1,10 +1,10 @@ # Installation on a Synology NAS -There are different ways to install NetAlertX on a Synology, including SSH-ing into the machine and using the command line. For this guide, we will use the Project option in Container manager. +There are different ways to install NetAlertX on a Synology, including SSH-ing into the machine and using the command line. For this guide, we will use the Project option in Container manager. ## Create the folder structure -The folders you are creating below will contain the configuration and the database. Back them up regularly. +The folders you are creating below will contain the configuration and the database. Back them up regularly. 1. Create a parent folder named `netalertx` 2. Create a `db` sub-folder @@ -29,23 +29,31 @@ The folders you are creating below will contain the configuration and the databa - Path: `/app_storage/netalertx` (will differ from yours) - Paste in the following template: + ```yaml version: "3" services: netalertx: container_name: netalertx # use the below line if you want to test the latest dev image - # image: "ghcr.io/jokob-sk/netalertx-dev:latest" - image: "ghcr.io/jokob-sk/netalertx:latest" - network_mode: "host" + # image: "ghcr.io/jokob-sk/netalertx-dev:latest" + image: "ghcr.io/jokob-sk/netalertx:latest" + network_mode: "host" restart: unless-stopped + cap_drop: # Drop all capabilities for enhanced security + - ALL + cap_add: # Re-add necessary capabilities + - NET_RAW + - NET_ADMIN + - NET_BIND_SERVICE volumes: - - local/path/config:/data/config - - local/path/db:/data/db - # (optional) useful for debugging if you have issues setting up the container - - local/path/logs:/tmp/log - # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured - - /etc/localtime:/etc/localtime:ro + - /app_storage/netalertx/config:/data/config + - /app_storage/netalertx/db:/data/db + # to sync with system time + - /etc/localtime:/etc/localtime:ro + tmpfs: + # All writable runtime state resides under /tmp; comment out to persist logs between restarts + - "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime" environment: - PORT=20211 ``` @@ -59,7 +67,7 @@ services: ```yaml volumes: - /volume1/app_storage/netalertx/config:/data/config - - /volume1/app_storage/netalertx/db:/data/db + - /volume1/app_storage/netalertx/db:/data/db # (optional) useful for debugging if you have issues setting up the container # - local/path/logs:/tmp/log <- commented out with # ⚠ ``` @@ -72,4 +80,12 @@ services: ![Build](./img/SYNOLOGY/09_Run_and_build.png) 10. Navigate to `:20211` (or your custom port). -11. Read the [Subnets](./SUBNETS.md) and [Plugins](/docs/PLUGINS.md) docs to complete your setup. \ No newline at end of file +11. Read the [Subnets](./SUBNETS.md) and [Plugins](/docs/PLUGINS.md) docs to complete your setup. + + +> [!TIP] +> If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> ```bash +> sudo chown -R 20211:20211 /local_data_dir +> sudo chmod -R a+rwx /local_data_dir +> ``` diff --git a/mkdocs.yml b/mkdocs.yml index e2cb4dc7..0f708c29 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,11 +9,11 @@ site_description: >- nav: - Home: index.md - - Installation: + - Installation: - Installation options: INSTALLATION.md - - Quick setup: INITIAL_SETUP.md + - Quick setup: INITIAL_SETUP.md - Docker: - - Docker Guide: DOCKER_INSTALLATION.md + - Docker Guide: DOCKER_INSTALLATION.md - Docker Compose: DOCKER_COMPOSE.md - Docker File Permissions: FILE_PERMISSIONS.md - Docker Updates: UPDATES.md @@ -25,24 +25,24 @@ nav: - Bare-metal (Experimental): HW_INSTALL.md - Migration Guide: MIGRATION.md - Help: - - Common issues: COMMON_ISSUES.md + - Common issues: COMMON_ISSUES.md - Setup: - Getting started: - Subnets: SUBNETS.md - - Enable Plugins: PLUGINS.md + - Enable Plugins: PLUGINS.md - Pi-hole Guide: PIHOLE_GUIDE.md - Home Assistant: HOME_ASSISTANT.md - Emails: SMTP.md - - Backups: BACKUPS.md + - Backups: BACKUPS.md - Security Features: SECURITY_FEATURES.md - Security Considerations: SECURITY.md - Advanced guides: - - Remote Networks: REMOTE_NETWORKS.md - - Notifications Guide: NOTIFICATIONS.md - - Name Resolution: NAME_RESOLUTION.md - - Authelia: AUTHELIA.md - - Performance: PERFORMANCE.md - - Reverse DNS: REVERSE_DNS.md + - Remote Networks: REMOTE_NETWORKS.md + - Notifications Guide: NOTIFICATIONS.md + - Name Resolution: NAME_RESOLUTION.md + - Authelia: AUTHELIA.md + - Performance: PERFORMANCE.md + - Reverse DNS: REVERSE_DNS.md - Reverse Proxy: REVERSE_PROXY.md - Webhooks (n8n): WEBHOOK_N8N.md - Workflows: WORKFLOWS.md @@ -63,6 +63,7 @@ nav: - Icons: ICONS.md - Network Topology: NETWORK_TREE.md - Troubleshooting: + - Common issues: COMMON_ISSUES.md - Inspecting Logs: LOGGING.md - Debugging Tips: DEBUG_TIPS.md - Debugging GraphQL: DEBUG_GRAPHQL.md @@ -83,8 +84,8 @@ nav: - Settings: SETTINGS_SYSTEM.md - Versions: VERSIONS.md - Icon and Type guessing: DEVICE_HEURISTICS.md - - API: - - Overview: API.md + - API: + - Overview: API.md - Devices Collection: API_DEVICES.md - Device: API_DEVICE.md - Sessions: API_SESSIONS.md @@ -98,9 +99,9 @@ nav: - GraphQL: API_GRAPHQL.md - DB query: API_DBQUERY.md - Tests: API_TESTS.md - - SUPERSEDED OLD API Overview: API_OLD.md + - SUPERSEDED OLD API Overview: API_OLD.md - Integrations: - - Webhook Secret: WEBHOOK_SECRET.md + - Webhook Secret: WEBHOOK_SECRET.md - Helper scripts: HELPER_SCRIPTS.md From 00e953a7ce06d76768bf76998d2ae5f02051089f Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 26 Nov 2025 09:52:12 +1100 Subject: [PATCH 02/34] DOCS: cleanup Signed-off-by: jokob-sk --- docs/COMMON_ISSUES.md | 120 +++++++++++++++++++++++++----------- docs/DEBUG_PLUGINS.md | 13 ++-- docs/DEBUG_TIPS.md | 12 +--- docs/FILE_PERMISSIONS.md | 19 ++++-- docs/WORKFLOWS_DEBUGGING.md | 16 ++--- mkdocs.yml | 14 ++--- 6 files changed, 124 insertions(+), 70 deletions(-) diff --git a/docs/COMMON_ISSUES.md b/docs/COMMON_ISSUES.md index d97e9954..4d196319 100755 --- a/docs/COMMON_ISSUES.md +++ b/docs/COMMON_ISSUES.md @@ -1,66 +1,114 @@ -### Loading... +# Troubleshooting Common Issues -Often if the application is misconfigured the `Loading...` dialog is continuously displayed. This is most likely caused by the backed failing to start. The **Maintenance -> Logs** section should give you more details on what's happening. If there is no exception, check the Portainer log, or start the container in the foreground (without the `-d` parameter) to observe any exceptions. It's advisable to enable `trace` or `debug`. Check the [Debug tips](./DEBUG_TIPS.md) on detailed instructions. +> [!TIP] +> Before troubleshooting, ensure you have set the correct [Debugging and LOG_LEVEL](./DEBUG_TIPS.md). -The issue might be related to the backend server, so please check [Debugging GraphQL issues](./DEBUG_API_SERVER.md). +--- -Please also check the browser logs (usually accessible by pressing `F12`): +## Docker Container Doesn't Start -1. Switch to the Console tab and refresh the page -2. Switch to teh Network tab and refresh the page - -If you are not sure how to resolve the errors yourself, please post screenshots of the above into the issue, or discord discussion, where your problem is being solved. - -### Incorrect SCAN_SUBNETS - -One of the most common issues is not configuring `SCAN_SUBNETS` correctly. If this setting is misconfigured you will only see one or two devices in your devices list after a scan. Please read the [subnets docs](./SUBNETS.md) carefully to resolve this. - -### Duplicate devices and notifications - -The app uses the MAC address as an unique identifier for devices. If a new MAC is detected a new device is added to the application and corresponding notifications are triggered. This means that if the MAC of an existing device changes, the device will be logged as a new device. You can usually prevent this from happening by changing the device configuration (in Android, iOS, or Windows) for your network. See the [Random Macs](./RANDOM_MAC.md) guide for details. +Initial setup issues are often caused by **missing permissions** or **incorrectly mapped volumes**. Always double-check your `docker run` or `docker-compose.yml` against the [official setup guide](./DOCKER_INSTALLATION.md) before proceeding. ### Permissions -Make sure you [File permissions](./FILE_PERMISSIONS.md) are set correctly. +Make sure your [file permissions](./FILE_PERMISSIONS.md) are correctly set: -* If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under `/tmp/log`. -* To solve permission issues you can try setting the owner and group of the `app.db` by executing the following on the host system: `docker exec netalertx chown -R www-data:www-data /data/db/app.db`. -* If still facing issues, try to map the app.db file (⚠ not folder) to `:/data/db/app.db` (see [docker-compose Examples](https://github.com/jokob-sk/NetAlertX/blob/main/dockerfiles/README.md#-docker-composeyml-examples) for details) +* If you encounter AJAX errors, cannot write to the database, or see an empty screen, check that permissions are correct and review the logs under `/tmp/log`. +* To fix permission issues with the database, update the owner and group of `app.db` as described in the [File Permissions guide](./FILE_PERMISSIONS.md). -### Container restarts / crashes +### Container Restarts / Crashes -* Check the logs for details. Often a required setting for a notification method is missing. +* Check the logs for details. Often, required settings are missing. +* For more detailed troubleshooting, see [Debug and Troubleshooting Tips](./DEBUG_TIPS.md). +* To observe errors directly, run the container in the foreground instead of `-d`: -### unable to resolve host +```bash +docker run --rm -it +``` -* Check that your `SCAN_SUBNETS` variable is using the correct mask and `--interface`. See the [subnets docs for details](./SUBNETS.md). +--- -### Invalid JSON +## Docker Container Starts, But the Application Misbehaves -Check the [Invalid JSON errors debug help](./DEBUG_INVALID_JSON.md) docs on how to proceed. +If the container starts but the app shows unexpected behavior, the cause is often **data corruption**, **incorrect configuration**, or **unexpected input data**. -### sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4 +### Continuous "Loading..." Screen -> sudo: unexpected child termination condition: 0 +A misconfigured application may display a persistent `Loading...` dialog. This is usually caused by the backend failing to start. -Resolution based on [this issue](https://github.com/linuxserver/docker-papermerge/issues/4#issuecomment-1003657581) +**Steps to troubleshoot:** + +1. Check **Maintenance → Logs** for exceptions. +2. If no exception is visible, check the Portainer logs. +3. Start the container in the foreground to observe exceptions. +4. Enable `trace` or `debug` logging for detailed output (see [Debug Tips](./DEBUG_TIPS.md)). +5. Verify that `GRAPHQL_PORT` is correctly configured. +6. Check browser logs (press `F12`): + + * **Console tab** → refresh the page + * **Network tab** → refresh the page + +If you are unsure how to resolve errors, provide screenshots or log excerpts in your issue report or Discord discussion. + +--- + +### Common Configuration Issues + +#### Incorrect `SCAN_SUBNETS` + +If `SCAN_SUBNETS` is misconfigured, you may see only a few devices in your device list after a scan. See the [Subnets Documentation](./SUBNETS.md) for proper configuration. + +#### Duplicate Devices and Notifications + +* Devices are identified by their **MAC address**. +* If a device's MAC changes, it will be treated as a new device, triggering notifications. +* Prevent this by adjusting your device configuration for Android, iOS, or Windows. See the [Random MACs Guide](./RANDOM_MAC.md). + +#### Unable to Resolve Host + +* Ensure `SCAN_SUBNETS` uses the correct mask and `--interface`. +* Refer to the [Subnets Documentation](./SUBNETS.md) for detailed guidance. + +#### Invalid JSON Errors + +* Follow the steps in [Invalid JSON Errors Debug Help](./DEBUG_INVALID_JSON.md). + +#### Sudo Execution Fails (e.g., on arpscan on Raspberry Pi 4) + +Error: ``` +sudo: unexpected child termination condition: 0 +``` + +**Resolution**: + +```bash wget ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.3-2_armhf.deb sudo dpkg -i libseccomp2_2.5.3-2_armhf.deb ``` -The link above will probably break in time too. Go to https://packages.debian.org/sid/armhf/libseccomp2/download to find the new version number and put that in the url. +> ⚠ The link may break over time. Check [Debian Packages](https://packages.debian.org/sid/armhf/libseccomp2/download) for the latest version. -### Only Router and own device show up +#### Only Router and Own Device Show Up -Make sure that the subnet and interface in `SCAN_SUBNETS` are correct. If your device/NAS has multiple ethernet ports, you probably need to change `eth0` to something else. +* Verify the subnet and interface in `SCAN_SUBNETS`. +* On devices with multiple Ethernet ports, you may need to change `eth0` to the correct interface. -### Losing my settings and devices after an update +#### Losing Settings or Devices After Update -If you lose your devices and/or settings after an update that means you don't have the `/data/db` and `/data/config` folders mapped to a permanent storage. That means every time you update these folders are re-created. Make sure you have the [volumes specified correctly](./DOCKER_COMPOSE.md) in your `docker-compose.yml` or run command. +* Ensure `/data/db` and `/data/config` are mapped to persistent storage. +* Without persistent volumes, these folders are recreated on every update. +* See [Docker Volumes Setup](./DOCKER_COMPOSE.md) for proper configuration. +#### Application Performance Issues -### The application is slow +Slowness can be caused by: + +* Incorrect settings (causing app restarts) → check `app.log`. +* Too many background processes → disable unnecessary scanners. +* Long scans → limit the number of scanned devices. +* Excessive disk operations or failing maintenance plugins. + +> See [Performance Tips](./PERFORMANCE.md) for detailed optimization steps. -Slowness is usually caused by incorrect settings (the app might restart, so check the `app.log`), too many background processes (disable unnecessary scanners), too long scans (limit the number of scanned devices), too many disk operations, or some maintenance plugins might have failed. See the [Performance tips](./PERFORMANCE.md) docs for details. \ No newline at end of file diff --git a/docs/DEBUG_PLUGINS.md b/docs/DEBUG_PLUGINS.md index 5df99769..e1a086c7 100755 --- a/docs/DEBUG_PLUGINS.md +++ b/docs/DEBUG_PLUGINS.md @@ -1,5 +1,8 @@ # Troubleshooting plugins +> [!TIP] +> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md). + ## High-level overview If a Plugin supplies data to the main app it's done either vie a SQL query or via a script that updates the `last_result.log` file in the plugin log folder (`app/log/plugins/`). @@ -9,7 +12,7 @@ For a more in-depth overview on how plugins work check the [Plugins development ### Prerequisites - Make sure you read and followed the specific plugin setup instructions. -- Ensure you have [debug enabled (see More Logging)](./DEBUG_TIPS.md) +- Ensure you have [debug enabled (see More Logging)](./DEBUG_TIPS.md) ### Potential issues @@ -47,9 +50,9 @@ Input data from the plugin might cause mapping issues in specific edge cases. Lo 17:31:05 [Plugins] history_to_insert count: 4 17:31:05 [Plugins] objects_to_insert count: 0 17:31:05 [Plugins] objects_to_update count: 4 -17:31:05 [Plugin utils] In pluginEvents there are 2 events with the status "watched-not-changed" -17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "missing-in-last-scan" -17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "watched-not-changed" +17:31:05 [Plugin utils] In pluginEvents there are 2 events with the status "watched-not-changed" +17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "missing-in-last-scan" +17:31:05 [Plugin utils] In pluginObjects there are 2 events with the status "watched-not-changed" 17:31:05 [Plugins] Mapping objects to database table: CurrentScan 17:31:05 [Plugins] SQL query for mapping: INSERT into CurrentScan ( "cur_MAC", "cur_IP", "cur_LastQuery", "cur_Name", "cur_Vendor", "cur_ScanMethod") VALUES ( ?, ?, ?, ?, ?, ?) 17:31:05 [Plugins] SQL sqlParams for mapping: [('01:01:01:01:01:01', '172.30.0.1', 0, 'aaaa', 'vvvvvvvvv', 'PIHOLE'), ('02:42:ac:1e:00:02', '172.30.0.2', 0, 'dddd', 'vvvvv2222', 'PIHOLE')] @@ -80,7 +83,7 @@ These values, if formatted correctly, will also show up in the UI: ### Sharing application state -Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong. +Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong. 1. Please set `LOG_LEVEL` to `trace` (Disable it once you have the info as this produces big log files). 2. Wait for the issue to occur. diff --git a/docs/DEBUG_TIPS.md b/docs/DEBUG_TIPS.md index 4362f32c..03c5d23e 100755 --- a/docs/DEBUG_TIPS.md +++ b/docs/DEBUG_TIPS.md @@ -55,15 +55,7 @@ services: ## 5. TMP mount directories to rule host out permission issues -Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. - -```bash -docker run --rm --network=host \ - -v /etc/localtime:/etc/localtime:ro \ - --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ - -e PORT=20211 \ - ghcr.io/jokob-sk/netalertx:latest -``` +Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. See teh [Permissions guide](./FILE_PERMISSIONS.md) for details. ## 6. Sharing application state @@ -79,4 +71,4 @@ Sometimes specific log sections are needed to debug issues. The Devices and Curr ## Common issues -See [Common issues](./COMMON_ISSUES.md) for details. +See [Common issues](./COMMON_ISSUES.md) for additional troubleshooting tips. diff --git a/docs/FILE_PERMISSIONS.md b/docs/FILE_PERMISSIONS.md index d634e516..0738d83b 100755 --- a/docs/FILE_PERMISSIONS.md +++ b/docs/FILE_PERMISSIONS.md @@ -1,8 +1,23 @@ # Managing File Permissions for NetAlertX on a Read-Only Container +Sometimes, permission issues arise if your existing host directories were created by a previous container running as root or another UID. The container will fail to start with "Permission Denied" errors. + > [!TIP] > NetAlertX runs in a **secure, read-only Alpine-based container** under a dedicated `netalertx` user (UID 20211, GID 20211). All writable paths are either mounted as **persistent volumes** or **`tmpfs` filesystems**. This ensures consistent file ownership and prevents privilege escalation. +Try starting the container with all data to be in non-persistent volumes. If this works, the issue might be related to the permissions of your persistent data mount locations on your server. + +```bash +docker run --rm --network=host \ + -v /etc/localtime:/etc/localtime:ro \ + --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \ + -e PORT=20211 \ + ghcr.io/jokob-sk/netalertx:latest +``` + +> [!WARNING] +> The above should be only used as a test - once the container restarts, all data is lost. + --- ## Writable Paths @@ -25,10 +40,6 @@ NetAlertX requires certain paths to be writable at runtime. These paths should b --- -## Fixing Permission Problems - -Sometimes, permission issues arise if your existing host directories were created by a previous container running as root or another UID. The container will fail to start with "Permission Denied" errors. - ### Solution 1. **Run the container once as root** (`--user "0"`) to allow it to correct permissions automatically: diff --git a/docs/WORKFLOWS_DEBUGGING.md b/docs/WORKFLOWS_DEBUGGING.md index 79eec5ba..29d83366 100755 --- a/docs/WORKFLOWS_DEBUGGING.md +++ b/docs/WORKFLOWS_DEBUGGING.md @@ -1,22 +1,22 @@ # Workflows debugging and troubleshooting > [!TIP] -> Before troubleshooting, please ensure you have [Debugging enabled](./DEBUG_TIPS.md). +> Before troubleshooting, please ensure you have the right [Debugging and LOG_LEVEL set](./DEBUG_TIPS.md). -Workflows are triggered by various events. These events are captured and listed in the _Integrations -> App Events_ section of the application. +Workflows are triggered by various events. These events are captured and listed in the _Integrations -> App Events_ section of the application. ## Troubleshooting triggers > [!NOTE] -> Workflow events are processed once every 5 seconds. However, if a scan or other background tasks are running, this can cause a delay up to a few minutes. +> Workflow events are processed once every 5 seconds. However, if a scan or other background tasks are running, this can cause a delay up to a few minutes. -If an event doesn't trigger a workflow as expected, check the _App Events_ section for the event. You can filter these by the ID of the device (`devMAC` or `devGUID`). +If an event doesn't trigger a workflow as expected, check the _App Events_ section for the event. You can filter these by the ID of the device (`devMAC` or `devGUID`). ![App events search](./img/WORKFLOWS/workflows_app_events_search.png) -Once you find the _Event Guid_ and _Object GUID_, use them to find relevant debug entries. +Once you find the _Event Guid_ and _Object GUID_, use them to find relevant debug entries. -Navigate to _Mainetenace -> Logs_ where you can filter the logs based on the _Event or Object GUID_. +Navigate to _Mainetenace -> Logs_ where you can filter the logs based on the _Event or Object GUID_. ![Log events search](./img/WORKFLOWS/workflows_logs_search.png) @@ -24,9 +24,9 @@ Below you can find some example `app.log` entries that will help you understand ```bash 16:27:03 [WF] Checking if '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggers the workflow 'Sample Device Update Workflow' -16:27:03 [WF] self.triggered 'False' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "insert"}' +16:27:03 [WF] self.triggered 'False' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "insert"}' 16:27:03 [WF] Checking if '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggers the workflow 'Location Change' -16:27:03 [WF] self.triggered 'True' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "update"}' +16:27:03 [WF] self.triggered 'True' for event '[[155], ['13f0ce26-1835-4c48-ae03-cdaf38f328fe'], [0], ['2025-04-02 05:26:56'], ['Devices'], ['050b6980-7af6-4409-950d-08e9786b7b33'], ['DEVICES'], ['00:11:32:ef:a5:6c'], ['192.168.1.82'], ['050b6980-7af6-4409-950d-08e9786b7b33'], [None], [0], [0], ['devPresentLastScan'], ['online'], ['update'], [None], [None], [None], [None]] and trigger {"object_type": "Devices", "event_type": "update"}' 16:27:03 [WF] Event with GUID '13f0ce26-1835-4c48-ae03-cdaf38f328fe' triggered the workflow 'Location Change' ``` diff --git a/mkdocs.yml b/mkdocs.yml index 0f708c29..ee42eef7 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,13 +65,13 @@ nav: - Troubleshooting: - Common issues: COMMON_ISSUES.md - Inspecting Logs: LOGGING.md - - Debugging Tips: DEBUG_TIPS.md - - Debugging GraphQL: DEBUG_GRAPHQL.md - - Debugging Invalid JSON: DEBUG_INVALID_JSON.md - - Debugging PHP: DEBUG_PHP.md - - Debugging Plugins: DEBUG_PLUGINS.md - - Debugging Web UI Port: WEB_UI_PORT_DEBUG.md - - Debugging Workflows: WORKFLOWS_DEBUGGING.md + - General Tips: DEBUG_TIPS.md + - API Server Issues: DEBUG_API_SERVER.md + - Invalid JSON Issues: DEBUG_INVALID_JSON.md + - PHP Issues: DEBUG_PHP.md + - Plugin Issues: DEBUG_PLUGINS.md + - Web UI Port Issues: WEB_UI_PORT_DEBUG.md + - Workflows Issues: WORKFLOWS_DEBUGGING.md - Development: - Plugin and app development: - Environment Setup: DEV_ENV_SETUP.md From d1be41eca4fb5413d6592dab4ab35b1fe0405b2f Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 26 Nov 2025 10:02:15 +1100 Subject: [PATCH 03/34] DOCS: cleanup Signed-off-by: jokob-sk --- docs/DEBUG_API_SERVER.md | 8 ++++---- docs/DOCKER_PORTAINER.md | 1 + docs/FILE_PERMISSIONS.md | 1 + docs/SYNOLOGY_GUIDE.md | 1 + docs/WEB_UI_PORT_DEBUG.md | 18 +++++++++--------- .../Init_check.png | Bin .../app_conf_graphql_port.png | Bin .../dev_console_graphql_json.png | Bin .../graphql_running_logs.png | Bin .../graphql_settings_port_token.png | Bin .../network_graphql.png | Bin mkdocs.yml | 4 ++-- 12 files changed, 18 insertions(+), 15 deletions(-) rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/Init_check.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/app_conf_graphql_port.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/dev_console_graphql_json.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/graphql_running_logs.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/graphql_settings_port_token.png (100%) mode change 100755 => 100644 rename docs/img/{DEBUG_GRAPHQL => DEBUG_API_SERVER}/network_graphql.png (100%) mode change 100755 => 100644 diff --git a/docs/DEBUG_API_SERVER.md b/docs/DEBUG_API_SERVER.md index 7a8fc361..2c3db557 100644 --- a/docs/DEBUG_API_SERVER.md +++ b/docs/DEBUG_API_SERVER.md @@ -1,12 +1,12 @@ # Debugging GraphQL server issues -The GraphQL server is an API middle layer, running on it's own port specified by `GRAPHQL_PORT`, to retrieve and show the data in the UI. It can also be used to retrieve data for custom third party integarions. Check the [API documentation](./API.md) for details. +The GraphQL server is an API middle layer, running on it's own port specified by `GRAPHQL_PORT`, to retrieve and show the data in the UI. It can also be used to retrieve data for custom third party integarions. Check the [API documentation](./API.md) for details. The most common issue is that the GraphQL server doesn't start properly, usually due to a **port conflict**. If you are running multiple NetAlertX instances, make sure to use **unique ports** by changing the `GRAPHQL_PORT` setting. The default is `20212`. ## How to update the `GRAPHQL_PORT` in case of issues -As a first troubleshooting step try changing the default `GRAPHQL_PORT` setting. Please remember NetAlertX is running on the host so any application uising the same port will cause issues. +As a first troubleshooting step try changing the default `GRAPHQL_PORT` setting. Please remember NetAlertX is running on the host so any application uising the same port will cause issues. ### Updating the setting via the Settings UI @@ -14,7 +14,7 @@ Ideally use the Settings UI to update the setting under General -> Core -> Graph ![GrapQL settings](./img/DEBUG_API_SERVER/graphql_settings_port_token.png) -You might need to temporarily stop other applications or NetAlertX instances causing conflicts to update the setting. The `API_TOKEN` is used to authenticate any API calls, including GraphQL requests. +You might need to temporarily stop other applications or NetAlertX instances causing conflicts to update the setting. The `API_TOKEN` is used to authenticate any API calls, including GraphQL requests. ### Updating the `app.conf` file @@ -24,7 +24,7 @@ If the UI is not accessible, you can directly edit the `app.conf` file in your ` ### Using a docker variable -All application settings can also be initialized via the `APP_CONF_OVERRIDE` docker env variable. +All application settings can also be initialized via the `APP_CONF_OVERRIDE` docker env variable. ```yaml ... diff --git a/docs/DOCKER_PORTAINER.md b/docs/DOCKER_PORTAINER.md index 6fb13ccc..8246411a 100755 --- a/docs/DOCKER_PORTAINER.md +++ b/docs/DOCKER_PORTAINER.md @@ -75,6 +75,7 @@ In the **Environment variables** section of Portainer, add the following: > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir diff --git a/docs/FILE_PERMISSIONS.md b/docs/FILE_PERMISSIONS.md index 0738d83b..772c9953 100755 --- a/docs/FILE_PERMISSIONS.md +++ b/docs/FILE_PERMISSIONS.md @@ -60,6 +60,7 @@ docker run -it --rm --name netalertx --user "0" \ > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir diff --git a/docs/SYNOLOGY_GUIDE.md b/docs/SYNOLOGY_GUIDE.md index dd6dec6d..192b964b 100755 --- a/docs/SYNOLOGY_GUIDE.md +++ b/docs/SYNOLOGY_GUIDE.md @@ -85,6 +85,7 @@ services: > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). +> > ```bash > sudo chown -R 20211:20211 /local_data_dir > sudo chmod -R a+rwx /local_data_dir diff --git a/docs/WEB_UI_PORT_DEBUG.md b/docs/WEB_UI_PORT_DEBUG.md index f58ec22c..04faf64e 100755 --- a/docs/WEB_UI_PORT_DEBUG.md +++ b/docs/WEB_UI_PORT_DEBUG.md @@ -2,7 +2,7 @@ The application uses the following default ports: -- **Web UI**: `20211` +- **Web UI**: `20211` - **GraphQL API**: `20212` The **Web UI** is served by an **nginx** server, while the **API backend** runs on a **Flask (Python)** server. @@ -25,8 +25,8 @@ Follow all of the below in order to disqualify potential causes of issues and to When opening an issue or debugging: -1. Include a screenshot of what you see when accessing `HTTP:///20211` (or your custom port) -1. [Follow steps 1, 2, 3, 4 on this page](./DEBUG_TIPS.md) +1. Include a screenshot of what you see when accessing `HTTP://:20211` (or your custom port) +1. [Follow steps 1, 2, 3, 4 on this page](./DEBUG_TIPS.md) 1. Execute the following in the container to see the processes and their ports and submit a screenshot of the result: - `sudo apk add lsof` - `sudo lsof -i` @@ -36,21 +36,21 @@ When opening an issue or debugging: ![lsof ports](./img/WEB_UI_PORT_DEBUG/container_port.png) -### 2. JavaScript issues +### 2. JavaScript issues Check for browser console (F12 browser dev console) errors + check different browsers. ### 3. Clear the app cache and cached JavaScript files -Refresh the browser cache (usually shoft + refresh), try a private window, or different browsers. Please also refresh the app cache by clicking the 🔃 (reload) button in the header of the application. +Refresh the browser cache (usually shoft + refresh), try a private window, or different browsers. Please also refresh the app cache by clicking the 🔃 (reload) button in the header of the application. ### 4. Disable proxies -If you have any reverse proxy or similar, try disabling it. +If you have any reverse proxy or similar, try disabling it. ### 5. Disable your firewall -If you are using a firewall, try to temporarily disabling it. +If you are using a firewall, try to temporarily disabling it. ### 6. Post your docker start details @@ -67,6 +67,6 @@ In the container execute and investigate: ### 8. Make sure permissions are correct > [!TIP] -> You can try to start the container without mapping the `/data/config` and `/data/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. +> You can try to start the container without mapping the `/data/config` and `/data/db` dirs and if the UI shows up then the issue is most likely related to your file system permissions or file ownership. -Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/data/db` and `app/config` directories. \ No newline at end of file +Please read the [Permissions troubleshooting guide](./FILE_PERMISSIONS.md) and provide a screesnhot of the permissions and ownership in the `/data/db` and `app/config` directories. \ No newline at end of file diff --git a/docs/img/DEBUG_GRAPHQL/Init_check.png b/docs/img/DEBUG_API_SERVER/Init_check.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/Init_check.png rename to docs/img/DEBUG_API_SERVER/Init_check.png diff --git a/docs/img/DEBUG_GRAPHQL/app_conf_graphql_port.png b/docs/img/DEBUG_API_SERVER/app_conf_graphql_port.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/app_conf_graphql_port.png rename to docs/img/DEBUG_API_SERVER/app_conf_graphql_port.png diff --git a/docs/img/DEBUG_GRAPHQL/dev_console_graphql_json.png b/docs/img/DEBUG_API_SERVER/dev_console_graphql_json.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/dev_console_graphql_json.png rename to docs/img/DEBUG_API_SERVER/dev_console_graphql_json.png diff --git a/docs/img/DEBUG_GRAPHQL/graphql_running_logs.png b/docs/img/DEBUG_API_SERVER/graphql_running_logs.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/graphql_running_logs.png rename to docs/img/DEBUG_API_SERVER/graphql_running_logs.png diff --git a/docs/img/DEBUG_GRAPHQL/graphql_settings_port_token.png b/docs/img/DEBUG_API_SERVER/graphql_settings_port_token.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/graphql_settings_port_token.png rename to docs/img/DEBUG_API_SERVER/graphql_settings_port_token.png diff --git a/docs/img/DEBUG_GRAPHQL/network_graphql.png b/docs/img/DEBUG_API_SERVER/network_graphql.png old mode 100755 new mode 100644 similarity index 100% rename from docs/img/DEBUG_GRAPHQL/network_graphql.png rename to docs/img/DEBUG_API_SERVER/network_graphql.png diff --git a/mkdocs.yml b/mkdocs.yml index ee42eef7..ba00a943 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,9 +63,9 @@ nav: - Icons: ICONS.md - Network Topology: NETWORK_TREE.md - Troubleshooting: - - Common issues: COMMON_ISSUES.md - - Inspecting Logs: LOGGING.md - General Tips: DEBUG_TIPS.md + - Common Issues: COMMON_ISSUES.md + - Inspecting Logs: LOGGING.md - API Server Issues: DEBUG_API_SERVER.md - Invalid JSON Issues: DEBUG_INVALID_JSON.md - PHP Issues: DEBUG_PHP.md From 8acb0a876a5fd625d8a29d1fe1a5abcbb1a782df Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 26 Nov 2025 10:20:19 +1100 Subject: [PATCH 04/34] DOCS: cleanup Signed-off-by: jokob-sk --- docs/DEBUG_INVALID_JSON.md | 6 +++--- docs/DEVICES_BULK_EDITING.md | 16 ++++++++-------- docs/DOCKER_PORTAINER.md | 8 ++++---- docs/FILE_PERMISSIONS.md | 8 ++++---- docs/SYNOLOGY_GUIDE.md | 8 ++++---- 5 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/DEBUG_INVALID_JSON.md b/docs/DEBUG_INVALID_JSON.md index bd66abfb..00b82b0b 100755 --- a/docs/DEBUG_INVALID_JSON.md +++ b/docs/DEBUG_INVALID_JSON.md @@ -3,13 +3,13 @@ Check the the HTTP response of the failing backend call by following these steps: - Open developer console in your browser (usually, e. g. for Chrome, key F12 on the keyboard). -- Follow the steps in this screenshot: +- Follow the steps in this screenshot: ![F12DeveloperConsole][F12DeveloperConsole] - Copy the URL causing the error and enter it in the address bar of your browser directly and hit enter. The copied URLs could look something like this (notice the query strings at the end): - - `http://:20211/api/table_devices.json?nocache=1704141103121` - - `http://:20211/php/server/devices.php?action=getDevicesTotals` + - `http://:20211/api/table_devices.json?nocache=1704141103121` + - `http://:20211/php/server/devices.php?action=getDevicesTotals` - Post the error response in the existing issue thread on GitHub or create a new issue and include the redacted response of the failing query. diff --git a/docs/DEVICES_BULK_EDITING.md b/docs/DEVICES_BULK_EDITING.md index d630a479..0e14081d 100755 --- a/docs/DEVICES_BULK_EDITING.md +++ b/docs/DEVICES_BULK_EDITING.md @@ -4,8 +4,8 @@ NetAlertX allows you to mass-edit devices via a CSV export and import feature, o ## UI multi edit -> [!NOTE] -> Make sure you have your backups saved and restorable before doing any mass edits. Check [Backup strategies](./BACKUPS.md). +> [!NOTE] +> Make sure you have your backups saved and restorable before doing any mass edits. Check [Backup strategies](./BACKUPS.md). You can select devices in the _Devices_ view by selecting devices to edit and then clicking the _Multi-edit_ button or via the _Maintenance_ > _Multi-Edit_ section. @@ -16,23 +16,23 @@ You can select devices in the _Devices_ view by selecting devices to edit and th The database and device structure may change with new releases. When using the CSV import functionality, ensure the format matches what the application expects. To avoid issues, you can first export the devices and review the column formats before importing any custom data. -> [!NOTE] +> [!NOTE] > As always, backup everything, just in case. -1. In _Maintenance_ > _Backup / Restore_ click the _CSV Export_ button. +1. In _Maintenance_ > _Backup / Restore_ click the _CSV Export_ button. 2. A `devices.csv` is generated in the `/config` folder -3. Edit the `devices.csv` file however you like. +3. Edit the `devices.csv` file however you like. ![Maintenance > CSV Export](./img/DEVICES_BULK_EDITING/MAINTENANCE_CSV_EXPORT.png) -> [!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: `/php/server/devices.php?action=ExportCSV` or via the `CSV Backup` plugin. (💡 You can schedule this) +> [!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: `:20211/php/server/devices.php?action=ExportCSV` or via the `CSV Backup` plugin. (💡 You can schedule this) ![Settings > CSV Backup](./img/DEVICES_BULK_EDITING/CSV_BACKUP_SETTINGS.png) ### File encoding format -> [!NOTE] +> [!NOTE] > Keep Linux line endings (suggested editors: Nano, Notepad++) ![Nodepad++ line endings](./img/DEVICES_BULK_EDITING/NOTEPAD++.png) diff --git a/docs/DOCKER_PORTAINER.md b/docs/DOCKER_PORTAINER.md index 8246411a..f588d058 100755 --- a/docs/DOCKER_PORTAINER.md +++ b/docs/DOCKER_PORTAINER.md @@ -76,10 +76,10 @@ In the **Environment variables** section of Portainer, add the following: > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). > -> ```bash -> sudo chown -R 20211:20211 /local_data_dir -> sudo chmod -R a+rwx /local_data_dir -> ``` +> `sudo chown -R 20211:20211 /local_data_dir` +> +> `sudo chmod -R a+rwx /local_data_dir1` +> --- diff --git a/docs/FILE_PERMISSIONS.md b/docs/FILE_PERMISSIONS.md index 772c9953..f8c3624b 100755 --- a/docs/FILE_PERMISSIONS.md +++ b/docs/FILE_PERMISSIONS.md @@ -61,10 +61,10 @@ docker run -it --rm --name netalertx --user "0" \ > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). > -> ```bash -> sudo chown -R 20211:20211 /local_data_dir -> sudo chmod -R a+rwx /local_data_dir -> ``` +> `sudo chown -R 20211:20211 /local_data_dir` +> +> `sudo chmod -R a+rwx /local_data_dir1` +> --- diff --git a/docs/SYNOLOGY_GUIDE.md b/docs/SYNOLOGY_GUIDE.md index 192b964b..5db5af2f 100755 --- a/docs/SYNOLOGY_GUIDE.md +++ b/docs/SYNOLOGY_GUIDE.md @@ -86,7 +86,7 @@ services: > [!TIP] > If you are facing permissions issues run the following commands on your server. This will change the owner and assure sufficient access to the database and config files that are stored in the `/local_data_dir/db` and `/local_data_dir/config` folders (replace `local_data_dir` with the location where your `/db` and `/config` folders are located). > -> ```bash -> sudo chown -R 20211:20211 /local_data_dir -> sudo chmod -R a+rwx /local_data_dir -> ``` +> `sudo chown -R 20211:20211 /local_data_dir` +> +> `sudo chmod -R a+rwx /local_data_dir1` +> From 067336dcc12fc0dd2909a36af620cce536bc8d32 Mon Sep 17 00:00:00 2001 From: "Carlos M. Silva" Date: Wed, 26 Nov 2025 20:05:57 +0100 Subject: [PATCH 05/34] Translated using Weblate (Portuguese (Portugal)) Currently translated at 68.2% (520 of 762 strings) Translation: NetAlertX/core Translate-URL: https://hosted.weblate.org/projects/pialert/core/pt_PT/ --- front/php/templates/language/pt_pt.json | 212 ++++++++++++------------ 1 file changed, 106 insertions(+), 106 deletions(-) mode change 100755 => 100644 front/php/templates/language/pt_pt.json diff --git a/front/php/templates/language/pt_pt.json b/front/php/templates/language/pt_pt.json old mode 100755 new mode 100644 index 449381be..12952b24 --- a/front/php/templates/language/pt_pt.json +++ b/front/php/templates/language/pt_pt.json @@ -60,7 +60,7 @@ "BackDevices_darkmode_disabled": "Modo Noturno Desativado", "BackDevices_darkmode_enabled": "Modo Noturno Ativado", "CLEAR_NEW_FLAG_description": "Se ativado (0 está desativado), dispositivos marcados comoNovo Dispositivo serão desmarcados se o limite (especificado em horas) exceder o tempo da Primeira Sessão .", - "CLEAR_NEW_FLAG_name": "", + "CLEAR_NEW_FLAG_name": "Limpar a flag nova", "CustProps_cant_remove": "Não é possível remover, é necessária pelo menos uma propriedade.", "DAYS_TO_KEEP_EVENTS_description": "Esta é uma definição de manutenção. Especifica o número de dias de entradas de eventos que serão mantidas. Todos os eventos mais antigos serão apagados periodicamente. Também se aplica ao Histórico de eventos do plug-in.", "DAYS_TO_KEEP_EVENTS_name": "Apagar eventos mais antigos que", @@ -73,10 +73,10 @@ "DevDetail_CustomProps_reset_info": "Isto irá remover as suas propriedades personalizadas neste dispositivo e repÃŽ-las para o valor predefinido.", "DevDetail_DisplayFields_Title": "Visualização", "DevDetail_EveandAl_AlertAllEvents": "Eventos de alerta", - "DevDetail_EveandAl_AlertDown": "", + "DevDetail_EveandAl_AlertDown": "Alerta apagado", "DevDetail_EveandAl_Archived": "Arquivado", "DevDetail_EveandAl_NewDevice": "Novo dispositivo", - "DevDetail_EveandAl_NewDevice_Tooltip": "", + "DevDetail_EveandAl_NewDevice_Tooltip": "Mostrará o estado “Novo” para o dispositivo e irá incluí-lo nas listas quando o filtro de “Novos dispositivos” estiver ativo. Não afeta as notificações.", "DevDetail_EveandAl_RandomMAC": "MAC Aleatório", "DevDetail_EveandAl_ScanCycle": "Rastrear dispositivo", "DevDetail_EveandAl_ScanCycle_a": "Rastear dispositivo", @@ -103,11 +103,11 @@ "DevDetail_MainInfo_Type": "Tipo", "DevDetail_MainInfo_Vendor": "Fornecedor", "DevDetail_MainInfo_mac": "MAC", - "DevDetail_NavToChildNode": "", + "DevDetail_NavToChildNode": "Expandir subelemento", "DevDetail_Network_Node_hover": "Selecione o dispositivo de rede principal ao qual o dispositivo atual está conectado, para preencher a árvore Rede.", "DevDetail_Network_Port_hover": "A porta a que este dispositivo está ligado no dispositivo de rede principal. Se for deixado vazio, é apresentado um ícone wifi na árvore Rede.", "DevDetail_Nmap_Scans": "Varreduras manuais do Nmap", - "DevDetail_Nmap_Scans_desc": "", + "DevDetail_Nmap_Scans_desc": "Aqui pode executar análises NMAP manuais. Também pode agendar análises NMAP automáticas regulares através do plugin Serviços & Portos (NMAP). Aceda à https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/nmap_scan para saber mais", "DevDetail_Nmap_buttonDefault": "Verificação predefinida", "DevDetail_Nmap_buttonDefault_text": "Scan padrão: Nmap verifica as 1.000 portas superiores para cada protocolo de digitalização solicitado. Isto atinge cerca de 93% das portas TCP e 49% das portas UDP. (cerca de 5 segundos)", "DevDetail_Nmap_buttonDetail": "Verificação Detalhada", @@ -155,34 +155,34 @@ "DevDetail_Tab_NmapTablePort": "Porta", "DevDetail_Tab_NmapTableService": "Serviço", "DevDetail_Tab_NmapTableState": "Estado", - "DevDetail_Tab_NmapTableText": "", + "DevDetail_Tab_NmapTableText": "Configurar uma programação em Definições", "DevDetail_Tab_NmapTableTime": "Tempo", "DevDetail_Tab_Plugins": "Plugins", "DevDetail_Tab_Presence": "Presença", "DevDetail_Tab_Sessions": "Sessões", "DevDetail_Tab_Tools": "Ferramentas", - "DevDetail_Tab_Tools_Internet_Info_Description": "", + "DevDetail_Tab_Tools_Internet_Info_Description": "A ferramenta de informações da Internet apresenta dados sobre a ligação à Internet, como endereço IP, cidade, país, código de área e fuso horário.", "DevDetail_Tab_Tools_Internet_Info_Error": "Ocorreu um erro", - "DevDetail_Tab_Tools_Internet_Info_Start": "", - "DevDetail_Tab_Tools_Internet_Info_Title": "", - "DevDetail_Tab_Tools_Nslookup_Description": "", - "DevDetail_Tab_Tools_Nslookup_Error": "", - "DevDetail_Tab_Tools_Nslookup_Start": "", - "DevDetail_Tab_Tools_Nslookup_Title": "", - "DevDetail_Tab_Tools_Speedtest_Description": "", - "DevDetail_Tab_Tools_Speedtest_Start": "", - "DevDetail_Tab_Tools_Speedtest_Title": "", - "DevDetail_Tab_Tools_Traceroute_Description": "", - "DevDetail_Tab_Tools_Traceroute_Error": "", - "DevDetail_Tab_Tools_Traceroute_Start": "", - "DevDetail_Tab_Tools_Traceroute_Title": "", - "DevDetail_Tools_WOL": "", - "DevDetail_Tools_WOL_noti": "", - "DevDetail_Tools_WOL_noti_text": "", - "DevDetail_Type_hover": "", - "DevDetail_Vendor_hover": "", - "DevDetail_WOL_Title": "", - "DevDetail_button_AddIcon": "", + "DevDetail_Tab_Tools_Internet_Info_Start": "Start Internet Info", + "DevDetail_Tab_Tools_Internet_Info_Title": "Internet Info", + "DevDetail_Tab_Tools_Nslookup_Description": "Nslookup é uma ferramenta de linha de comandos usada para consultar o Sistema de Nomes de Domínio (DNS). O DNS é um sistema que traduz nomes de domínio, como www.google.com, em endereços IP, como 172.217.0.142.", + "DevDetail_Tab_Tools_Nslookup_Error": "Erro: O endereço IP não é válido", + "DevDetail_Tab_Tools_Nslookup_Start": "Inicia Nslookup", + "DevDetail_Tab_Tools_Nslookup_Title": "Nslookup", + "DevDetail_Tab_Tools_Speedtest_Description": "A ferramenta Speedtest mede a velocidade de download, a velocidade de upload e a latência da ligação à Internet.", + "DevDetail_Tab_Tools_Speedtest_Start": "Iniciar Speedtest", + "DevDetail_Tab_Tools_Speedtest_Title": "Speedtest Online", + "DevDetail_Tab_Tools_Traceroute_Description": "Traceroute é um comando de diagnóstico de rede usado para rastrear o caminho que os pacotes de dados percorrem de um anfitrião para outro.

O comando utiliza o Protocolo de Mensagens de Controlo da Internet (ICMP) para enviar pacotes aos nós intermédios na rota, cada node intermédio responde com um pacote ICMP de tempo limite (TTL expirado).

O comando utiliza o Protocolo de Mensagens de Controlo da Internet (ICMP) para enviar pacotes aos nodes intermédios na rota, cada node intermédio responde com um pacote ICMP de tempo limite (TTL expirado).

A saída do comando traceroute apresenta o endereço IP de cada node intermédio na rota.

O comando traceroute pode ser usado para diagnosticar problemas de rede, como atrasos, perda de pacotes e rotas bloqueadas.", + "DevDetail_Tab_Tools_Traceroute_Error": "Erro: O endereço IP não é válido", + "DevDetail_Tab_Tools_Traceroute_Start": "Iniciar Traceroute", + "DevDetail_Tab_Tools_Traceroute_Title": "Traceroute", + "DevDetail_Tools_WOL": "Enviar comando WoL para ", + "DevDetail_Tools_WOL_noti": "Wake-on-LAN", + "DevDetail_Tools_WOL_noti_text": "O comando Wake-on-LAN é enviado para o endereço de broadcast. Se o destino não estiver na sub-rede/VLAN do NetAlertX, o dispositivo de destino não irá responder.", + "DevDetail_Type_hover": "O tipo do dispositivo. Se selecionar um dos dispositivos de rede predefinidos (por exemplo: AP, Firewall, Router, Switch
), eles aparecerão na configuração da árvore de rede como possíveis nós de rede principais.", + "DevDetail_Vendor_hover": "O fabricante deve ser detetado automaticamente. Pode substituir ou adicionar um valor personalizado.", + "DevDetail_WOL_Title": " Wake-on-LAN", + "DevDetail_button_AddIcon": "Adicionar novo ícone", "DevDetail_button_AddIcon_Help": "Cole uma tag HTML SVG ou um ícone de tag HTML Font Awesome. Leia a documentação sobre ícones para obter pormenores.", "DevDetail_button_AddIcon_Tooltip": "Adicione um novo ícone a este dispositivo que ainda não esteja disponível no menu suspenso.", "DevDetail_button_Delete": "Apagar dispositivo", @@ -199,23 +199,23 @@ "Device_MultiEdit_Backup": "", "Device_MultiEdit_Fields": "Editar campos:", "Device_MultiEdit_MassActions": "Ações em massa:", - "Device_MultiEdit_No_Devices": "", + "Device_MultiEdit_No_Devices": "Nenhum dispositivo selecionado.", "Device_MultiEdit_Tooltip": "Cuidadoso. Clicar aqui aplicará o valor à esquerda a todos os dispositivos selecionados acima.", "Device_Searchbox": "Procurar", - "Device_Shortcut_AllDevices": "", - "Device_Shortcut_AllNodes": "", + "Device_Shortcut_AllDevices": "Os meus dispositivos", + "Device_Shortcut_AllNodes": "Todos os Nodes", "Device_Shortcut_Archived": "Arquivado", "Device_Shortcut_Connected": "Conectado", "Device_Shortcut_Devices": "Dispositivos", "Device_Shortcut_DownAlerts": "Inativo e off-line", "Device_Shortcut_DownOnly": "Inativo", "Device_Shortcut_Favorites": "Favoritos", - "Device_Shortcut_NewDevices": "", + "Device_Shortcut_NewDevices": "Novo dispostivo", "Device_Shortcut_OnlineChart": "Presença do dispositivo", "Device_TableHead_AlertDown": "Alerta em baixo", "Device_TableHead_Connected_Devices": "Conexões", - "Device_TableHead_CustomProps": "", - "Device_TableHead_FQDN": "", + "Device_TableHead_CustomProps": "Propriedades / Ações", + "Device_TableHead_FQDN": "FQDN", "Device_TableHead_Favorite": "Favorito", "Device_TableHead_FirstSession": "Primeira sessão", "Device_TableHead_GUID": "GUID", @@ -230,11 +230,11 @@ "Device_TableHead_Name": "Nome", "Device_TableHead_NetworkSite": "Site da rede", "Device_TableHead_Owner": "Proprietário", - "Device_TableHead_ParentRelType": "", - "Device_TableHead_Parent_MAC": "", + "Device_TableHead_ParentRelType": "Tipo de relação", + "Device_TableHead_Parent_MAC": "Node de rede anterior", "Device_TableHead_Port": "Porta", "Device_TableHead_PresentLastScan": "Presença", - "Device_TableHead_ReqNicsOnline": "", + "Device_TableHead_ReqNicsOnline": "Exigir NICs online", "Device_TableHead_RowID": "ID da linha", "Device_TableHead_Rowid": "ID da linha", "Device_TableHead_SSID": "SSID", @@ -257,7 +257,7 @@ "ENCRYPTION_KEY_name": "Chave de encriptação", "Email_display_name": "Email", "Email_icon": "", - "Events_Loading": "", + "Events_Loading": "A carregar
", "Events_Periodselect_All": "Todas as informações", "Events_Periodselect_LastMonth": "Mês passado", "Events_Periodselect_LastWeek": "Semana passada", @@ -268,7 +268,7 @@ "Events_Shortcut_DownAlerts": "Alertas de queda", "Events_Shortcut_Events": "Eventos", "Events_Shortcut_MissSessions": "Sessões ausentes", - "Events_Shortcut_NewDevices": "", + "Events_Shortcut_NewDevices": "Novos dispositivos", "Events_Shortcut_Sessions": "Sessões", "Events_Shortcut_VoidSessions": "Sessões anuladas", "Events_TableHead_AdditionalInfo": "Informação adicional", @@ -278,7 +278,7 @@ "Events_TableHead_Disconnection": "Desconexão", "Events_TableHead_Duration": "Duração", "Events_TableHead_DurationOrder": "Duração do pedido", - "Events_TableHead_EventType": "", + "Events_TableHead_EventType": "Tipos de eventos", "Events_TableHead_IP": "IP", "Events_TableHead_IPOrder": "Pedido de IP", "Events_TableHead_Order": "Ordem", @@ -294,15 +294,15 @@ "GRAPHQL_PORT_name": "Porta GraphQL", "Gen_Action": "Ação", "Gen_Add": "Adicionar", - "Gen_AddDevice": "", + "Gen_AddDevice": "Adicionar dispositivo", "Gen_Add_All": "Adicionar todos", - "Gen_All_Devices": "", + "Gen_All_Devices": "Todos os dispostivos", "Gen_AreYouSure": "Tem certeza?", "Gen_Backup": "Executar backup", "Gen_Cancel": "Cancelar", "Gen_Change": "Alterar", "Gen_Copy": "Executar", - "Gen_CopyToClipboard": "", + "Gen_CopyToClipboard": "Copiar para a área de transferência", "Gen_DataUpdatedUITakesTime": "OK - Pode levar um tempo para a interface do utilizador ser atualizada se uma verificação estiver em execução.", "Gen_Delete": "Apagar", "Gen_DeleteAll": "Apagar todos", @@ -310,9 +310,9 @@ "Gen_Error": "Erro", "Gen_Filter": "Filtro", "Gen_Generate": "Gerar", - "Gen_InvalidMac": "", + "Gen_InvalidMac": "Endereço MAC Inválido.", "Gen_LockedDB": "ERRO - A base de dados pode estar bloqueada - Verifique F12 Ferramentas de desenvolvimento -> Console ou tente mais tarde.", - "Gen_NetworkMask": "", + "Gen_NetworkMask": "Máscara de Rede", "Gen_Offline": "Offline", "Gen_Okay": "Ok", "Gen_Online": "Online", @@ -329,8 +329,8 @@ "Gen_Select": "Selecionar", "Gen_SelectIcon": "", "Gen_SelectToPreview": "Selecionar para pré-visualizar", - "Gen_Selected_Devices": "", - "Gen_Subnet": "", + "Gen_Selected_Devices": "Seleciona dispostivos:", + "Gen_Subnet": "Sub-rede", "Gen_Switch": "Trocar", "Gen_Upd": "Atualizado com sucesso", "Gen_Upd_Fail": "A atualização falhou", @@ -344,14 +344,14 @@ "General_display_name": "Geral", "General_icon": "", "HRS_TO_KEEP_NEWDEV_description": "", - "HRS_TO_KEEP_NEWDEV_name": "", + "HRS_TO_KEEP_NEWDEV_name": "Remover novos dispostivos depois", "HRS_TO_KEEP_OFFDEV_description": "", "HRS_TO_KEEP_OFFDEV_name": "Apagar dispositivos offline após", "LOADED_PLUGINS_description": "Quais plugins carregar. Adicionar plugins pode deixar a aplicação lenta. Leia mais sobre quais plugins precisam ser ativados, tipos ou opções de escaneamento na documentação de plugins. Plugins descarregados perderão as suas configurações. Somente plugins desativados podem ser descarregados.", "LOADED_PLUGINS_name": "Plugins carregados", "LOG_LEVEL_description": "Esta definição permite um registo mais detalhado. Útil para depurar eventos gravados na base de dados.", "LOG_LEVEL_name": "Imprimir registo adicional", - "Loading": "", + "Loading": "A carregar
", "Login_Box": "Introduza a sua palavra-passe", "Login_Default_PWD": "A palavra-passe predefinida “123456” ainda está ativa.", "Login_Info": "As palavra-passes são definidas por meio do plugin Definir palavra-passe. Verifique a documentação do SETPWD se tiver problemas para fazer login.", @@ -369,20 +369,20 @@ "Maint_PurgeLog": "Limpar o registo", "Maint_RestartServer": "Reiniciar o servidor", "Maint_Restart_Server_noti_text": "Tem certeza de que deseja reiniciar o servidor backend? Isto pode causar inconsistência na app. Faça primeiro um backup da sua configuração.

Nota: Isto pode levar alguns minutos.", - "Maintenance_InitCheck": "", - "Maintenance_InitCheck_Checking": "", - "Maintenance_InitCheck_QuickSetupGuide": "", - "Maintenance_InitCheck_Success": "", - "Maintenance_ReCheck": "", + "Maintenance_InitCheck": "Verificação inicial", + "Maintenance_InitCheck_Checking": "A verificar
", + "Maintenance_InitCheck_QuickSetupGuide": "Certifique-se de que seguiu o guia de configuração rápida.", + "Maintenance_InitCheck_Success": "Aplicação inicializada com sucesso!", + "Maintenance_ReCheck": "Verificar novamente", "Maintenance_Running_Version": "Versão instalada", "Maintenance_Status": "Situação", "Maintenance_Title": "Ferramentas de manutenção", - "Maintenance_Tool_DownloadConfig": "", + "Maintenance_Tool_DownloadConfig": "Exportar Definições", "Maintenance_Tool_DownloadConfig_text": "Descarregue um backup completo da configuração das Configurações armazenada no ficheiro app.conf.", - "Maintenance_Tool_DownloadWorkflows": "", - "Maintenance_Tool_DownloadWorkflows_text": "", - "Maintenance_Tool_ExportCSV": "", - "Maintenance_Tool_ExportCSV_noti": "", + "Maintenance_Tool_DownloadWorkflows": "Exportar Workflows", + "Maintenance_Tool_DownloadWorkflows_text": "Descarregue uma cópia completa de segurança dos seus Workflows armazenados no ficheiro workflows.json .", + "Maintenance_Tool_ExportCSV": "Exportar dispostivos (csv)", + "Maintenance_Tool_ExportCSV_noti": "Exportar dispostivos (csv)", "Maintenance_Tool_ExportCSV_noti_text": "Tem a certeza de que pretende gerar um ficheiro CSV?", "Maintenance_Tool_ExportCSV_text": "Gere um ficheiro CSV (valor separado por vírgula) contendo a lista de dispositivos, incluindo os relacionamentos de rede entre os nós de rede e os dispositivos conectados. Também pode acionar isto a aceder esta URL your_NetAlertX_url/php/server/devices.php?action=ExportCSV ou ativando o plugin CSV Backup.", "Maintenance_Tool_ImportCSV": "Importação de dispositivos (csv)", @@ -413,31 +413,31 @@ "Maintenance_Tool_del_ActHistory_noti": "Apagar atividade de rede", "Maintenance_Tool_del_ActHistory_noti_text": "Tem certeza de que deseja redefinir a atividade da rede?", "Maintenance_Tool_del_ActHistory_text": "O gráfico de atividade da rede é redefinido. Isto não afeta os eventos.", - "Maintenance_Tool_del_alldev": "", - "Maintenance_Tool_del_alldev_noti": "", + "Maintenance_Tool_del_alldev": "Remover todos os dispositivo", + "Maintenance_Tool_del_alldev_noti": "Remover dispositivos", "Maintenance_Tool_del_alldev_noti_text": "Tem certeza de que deseja apagar todos os dispositivos?", "Maintenance_Tool_del_alldev_text": "Antes de usar esta função, faça um backup. Apagar não pode ser desfeito. Todos os dispositivos serão apagados da base de dados.", "Maintenance_Tool_del_allevents": "Apagar eventos (Repor presença)", "Maintenance_Tool_del_allevents30": "Apagar todos os eventos com mais que 30 dias", "Maintenance_Tool_del_allevents30_noti": "Apagar eventos", - "Maintenance_Tool_del_allevents30_noti_text": "", + "Maintenance_Tool_del_allevents30_noti_text": "Tem a certeza de que pretende eliminar todos os Eventos com mais de 30 dias? Isto repõe a presença de todos os dispositivos.", "Maintenance_Tool_del_allevents30_text": "Antes de utilizar esta função, faça uma cópia de segurança. Apagar não pode ser anulado. Todos os eventos com mais que 30 dias na base de dados serão eliminados. Nesse momento, a presença de todos os dispositivos será reiniciada. Este facto pode dar origem a sessões inválidas. Isto significa que os dispositivos são apresentados como “presentes” apesar de estarem offline. Uma verificação enquanto o dispositivo em questão está online resolve o problema.", "Maintenance_Tool_del_allevents_noti": "Apagar eventos", - "Maintenance_Tool_del_allevents_noti_text": "", + "Maintenance_Tool_del_allevents_noti_text": "Tem a certeza de que pretende eliminar todos os Eventos? Isto repõe a presença de todos os dispositivos.", "Maintenance_Tool_del_allevents_text": "Antes de usar esta função, faça um backup. Apagar não pode ser desfeito. Todos os eventos na base de dados serão apagados. Nesse momento, a presença de todos os dispositivos será redefinida. Isto pode levar a sessões inválidas. Isto significa que os dispositivos são exibidos como \"presente\" embora estejam offline. Uma varredura enquanto o dispositivo em questão é on-line resolve o problema.", - "Maintenance_Tool_del_empty_macs": "", - "Maintenance_Tool_del_empty_macs_noti": "", + "Maintenance_Tool_del_empty_macs": "Eliminar dispositivos com endereços MACs vazios", + "Maintenance_Tool_del_empty_macs_noti": "Elimitar dispositivos", "Maintenance_Tool_del_empty_macs_noti_text": "Tem certeza que deseja apagar todos os dispositivos com endereços MAC vazios?
(talvez prefira arquivá-los)", "Maintenance_Tool_del_empty_macs_text": "Antes de usar esta função, faça um backup. Apagar não pode ser desfeito. Todos os dispositivos sem MAC serão apagados da base de dados.", "Maintenance_Tool_del_selecteddev": "Apagar dispositivos selecionados", "Maintenance_Tool_del_selecteddev_text": "Antes de usar esta função, faça um backup. Apagar não pode ser desfeito. Dispositivos selecionados serão apagados da base de dados.", - "Maintenance_Tool_del_unknowndev": "", - "Maintenance_Tool_del_unknowndev_noti": "", + "Maintenance_Tool_del_unknowndev": "Eliminar dispositivos desconhecidos", + "Maintenance_Tool_del_unknowndev_noti": "Eliminar dispositivos desconhecidos", "Maintenance_Tool_del_unknowndev_noti_text": "Tem certeza que deseja apagar todos (desconhecidos) e (nome não encontrados) dispositivos?", "Maintenance_Tool_del_unknowndev_text": "Antes de usar esta função, faça um backup. Apagar não pode ser desfeito. Todos os dispositivos nomeados (não conhecidos) serão apagados da base de dados.", "Maintenance_Tool_displayed_columns_text": "Altere a visibilidade e a ordem das colunas na página Dispositivos.", "Maintenance_Tool_drag_me": "Arraste-me para reordenar colunas.", - "Maintenance_Tool_order_columns_text": "", + "Maintenance_Tool_order_columns_text": "Maintenance_Tool_order_columns_text", "Maintenance_Tool_purgebackup": "Limpar cópias de segurança", "Maintenance_Tool_purgebackup_noti": "Limpar cópias de segurança", "Maintenance_Tool_purgebackup_noti_text": "Tem certeza que deseja apagar todos os backups exceto os últimos 3?", @@ -450,13 +450,13 @@ "Maintenance_Tool_upgrade_database_noti_text": "Tem certeza de que deseja atualizar a base de dados?
(talvez prefira arquivá-la)", "Maintenance_Tool_upgrade_database_text": "Este botão atualizará a base de dados para ativar o gráfico Atividade de rede nas últimas 12 horas. Faça uma cópia de segurança da sua base de dados em caso de problemas.", "Maintenance_Tools_Tab_BackupRestore": "Backup / Restauração", - "Maintenance_Tools_Tab_Logging": "", + "Maintenance_Tools_Tab_Logging": "Logs", "Maintenance_Tools_Tab_Settings": "Configurações", "Maintenance_Tools_Tab_Tools": "Ferramentas", "Maintenance_Tools_Tab_UISettings": "Configurações de interface", "Maintenance_arp_status": "Estado de digitalização", "Maintenance_arp_status_off": "está atualmente desativado", - "Maintenance_arp_status_on": "", + "Maintenance_arp_status_on": "Scan em curso", "Maintenance_built_on": "Construído em", "Maintenance_current_version": "Você está atualizado. Confira o que estou a trabalhar em.", "Maintenance_database_backup": "Backups DB", @@ -467,8 +467,8 @@ "Maintenance_database_rows": "Tabela (linhas)", "Maintenance_database_size": "Tamanho da base de dados", "Maintenance_lang_selector_apply": "Aplicar", - "Maintenance_lang_selector_empty": "", - "Maintenance_lang_selector_lable": "", + "Maintenance_lang_selector_empty": "Escolha a lingua", + "Maintenance_lang_selector_lable": "Escolha a lingua", "Maintenance_lang_selector_text": "A mudança ocorre no lado do cliente, por isso afeta apenas o navegador atual.", "Maintenance_new_version": "Uma nova versão está disponível. Confira as notas de lançamento.", "Maintenance_themeselector_apply": "Aplicar", @@ -476,10 +476,10 @@ "Maintenance_themeselector_lable": "Selecionar Skin", "Maintenance_themeselector_text": "A mudança ocorre no lado do servidor, por isso afeta todos os dispositivos em uso.", "Maintenance_version": "Atualizações de apps", - "NETWORK_DEVICE_TYPES_description": "", + "NETWORK_DEVICE_TYPES_description": "Quais os tipos de dispositivos que podem ser usados como dispositivos de rede na vista de Rede. O tipo de dispositivo tem de corresponder exatamente à definição Type um dispositivo específico em Detalhes do dispositivo. Adicione-o ao dispositivo através do botão +. Não remova tipos existentes, apenas adicione novos.", "NETWORK_DEVICE_TYPES_name": "Tipos de dispositivo de rede", "Navigation_About": "Sobre a", - "Navigation_AppEvents": "", + "Navigation_AppEvents": "Eventos de aplicações", "Navigation_Devices": "Dispositivos", "Navigation_Donations": "Doações", "Navigation_Events": "Eventos", @@ -489,38 +489,38 @@ "Navigation_Network": "Rede", "Navigation_Notifications": "Notificações", "Navigation_Plugins": "Plugins", - "Navigation_Presence": "", - "Navigation_Report": "", - "Navigation_Settings": "", - "Navigation_SystemInfo": "", - "Navigation_Workflows": "", - "Network_Assign": "", - "Network_Cant_Assign": "", - "Network_Cant_Assign_No_Node_Selected": "", - "Network_Configuration_Error": "", - "Network_Connected": "", - "Network_Devices": "", - "Network_ManageAdd": "", - "Network_ManageAdd_Name": "", - "Network_ManageAdd_Name_text": "", - "Network_ManageAdd_Port": "", - "Network_ManageAdd_Port_text": "", - "Network_ManageAdd_Submit": "", - "Network_ManageAdd_Type": "", - "Network_ManageAdd_Type_text": "", - "Network_ManageAssign": "", - "Network_ManageDel": "", - "Network_ManageDel_Name": "", - "Network_ManageDel_Name_text": "", - "Network_ManageDel_Submit": "", - "Network_ManageDevices": "", - "Network_ManageEdit": "", - "Network_ManageEdit_ID": "", - "Network_ManageEdit_ID_text": "", - "Network_ManageEdit_Name": "", - "Network_ManageEdit_Name_text": "", - "Network_ManageEdit_Port": "", - "Network_ManageEdit_Port_text": "", + "Navigation_Presence": "Presença", + "Navigation_Report": "Reports enviados", + "Navigation_Settings": "Definições", + "Navigation_SystemInfo": "Informação de sistema", + "Navigation_Workflows": "Workflows", + "Network_Assign": "Conectar ao nodo de network em cima", + "Network_Cant_Assign": "Não é possível atribuir o node raiz da Internet como um node folha filho.", + "Network_Cant_Assign_No_Node_Selected": "Não é possível atribuir, nenhum node pai selecionado.", + "Network_Configuration_Error": "Erro de configuração", + "Network_Connected": "Dispositivos conectados", + "Network_Devices": "Dispositivos de rede", + "Network_ManageAdd": "Adicionar dispositivo", + "Network_ManageAdd_Name": "Nome do dispositivo", + "Network_ManageAdd_Name_text": "Nome sem caracteres especiais", + "Network_ManageAdd_Port": "Contagem de portas", + "Network_ManageAdd_Port_text": "Deixe em branco para Wi-Fi e Powerline", + "Network_ManageAdd_Submit": "Adicionar dispositivo", + "Network_ManageAdd_Type": "Tipo de dispositivo", + "Network_ManageAdd_Type_text": "-- Selecionar Tipo --", + "Network_ManageAssign": "Asignar", + "Network_ManageDel": "Eliminar dispositivo", + "Network_ManageDel_Name": "Dispositivo a eliminar", + "Network_ManageDel_Name_text": "-- Seleciona dispositivo --", + "Network_ManageDel_Submit": "Eliminar", + "Network_ManageDevices": "Gerir dispositivos", + "Network_ManageEdit": "Actualizar dispositivos", + "Network_ManageEdit_ID": "Dispositivos a actualizar", + "Network_ManageEdit_ID_text": "-- Selecionar dispositivo para edição --", + "Network_ManageEdit_Name": "Novo nome de dispositivo", + "Network_ManageEdit_Name_text": "Nome sem caracteres especiais", + "Network_ManageEdit_Port": " Nova contagem de portas", + "Network_ManageEdit_Port_text": "Deixe em branco para Wi-Fi e Powerline.", "Network_ManageEdit_Submit": "", "Network_ManageEdit_Type": "", "Network_ManageEdit_Type_text": "", @@ -761,4 +761,4 @@ "settings_system_label": "", "settings_update_item_warning": "", "test_event_tooltip": "Guarde as alterações antes de testar as definições." -} \ No newline at end of file +} From b9d3f430fe1c203b05e0ab3c5859f818902ff4d5 Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Thu, 27 Nov 2025 12:10:33 +1100 Subject: [PATCH 06/34] FE: regex validation for cron run schedules Signed-off-by: jokob-sk --- docs/API.md | 2 +- docs/DEVICE_MANAGEMENT.md | 22 +- docs/HELPER_SCRIPTS.md | 6 +- docs/HW_INSTALL.md | 9 +- docs/MIGRATION.md | 12 +- docs/SESSION_INFO.md | 80 +++--- docs/UPDATES.md | 11 +- front/css/app.css | 199 +++++++------- front/js/modal.js | 57 ++-- front/js/settings_utils.js | 268 ++++++++++--------- front/js/ui_components.js | 141 +++++----- front/multiEditCore.php | 103 +++---- front/php/templates/language/ar_ar.json | 1 + front/php/templates/language/ca_ca.json | 1 + front/php/templates/language/cs_cz.json | 1 + front/php/templates/language/de_de.json | 1 + front/php/templates/language/en_us.json | 1 + front/php/templates/language/es_es.json | 1 + front/php/templates/language/fa_fa.json | 1 + front/php/templates/language/fr_fr.json | 1 + front/php/templates/language/it_it.json | 1 + front/php/templates/language/ja_jp.json | 1 + front/php/templates/language/nb_no.json | 1 + front/php/templates/language/pl_pl.json | 1 + front/php/templates/language/pt_br.json | 1 + front/php/templates/language/pt_pt.json | 1 + front/php/templates/language/ru_ru.json | 1 + front/php/templates/language/sv_sv.json | 1 + front/php/templates/language/tr_tr.json | 1 + front/php/templates/language/uk_ua.json | 1 + front/php/templates/language/zh_cn.json | 1 + front/plugins/__template/config.json | 2 +- front/plugins/_publisher_mqtt/config.json | 2 +- front/plugins/arp_scan/config.json | 2 +- front/plugins/asuswrt_import/config.json | 2 +- front/plugins/avahi_scan/config.json | 2 +- front/plugins/csv_backup/config.json | 2 +- front/plugins/db_cleanup/config.json | 2 +- front/plugins/ddns_update/config.json | 2 +- front/plugins/dhcp_leases/config.json | 2 +- front/plugins/dhcp_servers/config.json | 2 +- front/plugins/dig_scan/config.json | 2 +- front/plugins/freebox/config.json | 2 +- front/plugins/icmp_scan/config.json | 2 +- front/plugins/internet_ip/config.json | 2 +- front/plugins/internet_speedtest/config.json | 2 +- front/plugins/ipneigh/config.json | 2 +- front/plugins/maintenance/config.json | 2 +- front/plugins/mikrotik_scan/config.json | 2 +- front/plugins/nbtscan_scan/config.json | 2 +- front/plugins/nmap_dev_scan/config.json | 2 +- front/plugins/nmap_scan/config.json | 2 +- front/plugins/nslookup_scan/config.json | 2 +- front/plugins/omada_sdn_imp/config.json | 2 +- front/plugins/omada_sdn_openapi/config.json | 2 +- front/plugins/pihole_api_scan/config.json | 2 +- front/plugins/pihole_scan/config.json | 2 +- front/plugins/snmp_discovery/config.json | 2 +- front/plugins/sync/config.json | 2 +- front/plugins/unifi_api_import/config.json | 4 +- front/plugins/vendor_update/config.json | 2 +- front/plugins/wake_on_lan/config.json | 2 +- front/plugins/website_monitor/config.json | 2 +- front/settings.php | 263 +++++++++--------- 64 files changed, 666 insertions(+), 592 deletions(-) diff --git a/docs/API.md b/docs/API.md index 8c9c3767..3ad69a96 100755 --- a/docs/API.md +++ b/docs/API.md @@ -1,4 +1,4 @@ -# NetAlertX API Documentation +# API Documentation This API provides programmatic access to **devices, events, sessions, metrics, network tools, and sync** in NetAlertX. It is implemented as a **REST and GraphQL server**. All requests require authentication via **API Token** (`API_TOKEN` setting) unless explicitly noted. For example, to authorize a GraphQL request, you need to use a `Authorization: Bearer API_TOKEN` header as per example below: diff --git a/docs/DEVICE_MANAGEMENT.md b/docs/DEVICE_MANAGEMENT.md index dc95ee7e..f106da24 100755 --- a/docs/DEVICE_MANAGEMENT.md +++ b/docs/DEVICE_MANAGEMENT.md @@ -1,8 +1,8 @@ -# NetAlertX - Device Management +# Device Management The Main Info section is where most of the device identifiable information is stored and edited. Some of the information is autodetected via various plugins. Initial values for most of the fields can be specified in the `NEWDEV` plugin. -> [!NOTE] +> [!NOTE] > > You can multi-edit devices by selecting them in the main Devices view, from the Mainetence section, or via the CSV Export functionality under Maintenance. More info can be found in the [Devices Bulk-editing docs](./DEVICES_BULK_EDITING.md). @@ -14,23 +14,23 @@ 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. - - **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. + - **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`, - `Laptop`, `TV`, `router`, etc.) or add a new device type. If you want the device to act as a **Network device** (and be able to be a network node in the Network view), select a type under Network Devices or add a new Network Device type in Settings. More information can be found in the [Network Setup docs](./NETWORK_TREE.md). + `Laptop`, `TV`, `router`, etc.) or add a new device type. If you want the device to act as a **Network device** (and be able to be a network node in the Network view), select a type under Network Devices or add a new Network Device type in Settings. More information can be found in the [Network Setup docs](./NETWORK_TREE.md). - **Vendor**: The manufacturing vendor. Automatically updated by NetAlertX when empty or unknown, can be edited. - **Group**: Select a group (`Always on`, `Personal`, `Friends`, etc.) or type your own Group name. - - **Location**: Select the location, usually a room, where the device is located (`Kitchen`, `Attic`, `Living room`, etc.) or add a custom Location. + - **Location**: Select the location, usually a room, where the device is located (`Kitchen`, `Attic`, `Living room`, etc.) or add a custom Location. - **Comments**: Add any comments for the device, such as a serial number, or maintenance information. -> [!NOTE] +> [!NOTE] > -> Please note the above usage of the fields are only suggestions. You can use most of these fields for other purposes, such as storing the network interface, company owning a device, or similar. +> Please note the above usage of the fields are only suggestions. You can use most of these fields for other purposes, such as storing the network interface, company owning a device, or similar. ## Dummy devices -You can create dummy devices from the Devices listing screen. +You can create dummy devices from the Devices listing screen. ![Create Dummy Device](./img/DEVICE_MANAGEMENT/Devices_CreateDummyDevice.png) @@ -39,12 +39,12 @@ The **MAC** field and the **Last IP** field will then become editable. ![Save Dummy Device](./img/DEVICE_MANAGEMENT/DeviceEdit_SaveDummyDevice.png) -> [!NOTE] +> [!NOTE] > > You can couple this with the `ICMP` plugin which can be used to monitor the status of these devices, if they are actual devices reachable with the `ping` command. If not, you can use a loopback IP address so they appear online, such as `0.0.0.0` or `127.0.0.1`. -## Copying data from an existing device. +## Copying data from an existing device. -To speed up device population you can also copy data from an existing device. This can be done from the **Tools** tab on the Device details. +To speed up device population you can also copy data from an existing device. This can be done from the **Tools** tab on the Device details. diff --git a/docs/HELPER_SCRIPTS.md b/docs/HELPER_SCRIPTS.md index 628ea19b..fa4ea6b3 100755 --- a/docs/HELPER_SCRIPTS.md +++ b/docs/HELPER_SCRIPTS.md @@ -1,4 +1,4 @@ -# NetAlertX Community Helper Scripts Overview +# Community Helper Scripts Overview This page provides an overview of community-contributed scripts for NetAlertX. These scripts are not actively maintained and are provided as-is. @@ -14,8 +14,8 @@ You can find all scripts in this [scripts GitHub folder](https://github.com/joko ## Important Notes -> [!NOTE] -> These scripts are community-supplied and not actively maintained. Use at your own discretion. +> [!NOTE] +> These scripts are community-supplied and not actively maintained. Use at your own discretion. For detailed usage instructions, refer to each script's documentation in each [scripts GitHub folder](https://github.com/jokob-sk/NetAlertX/tree/main/scripts). diff --git a/docs/HW_INSTALL.md b/docs/HW_INSTALL.md index 814230da..e34535cf 100755 --- a/docs/HW_INSTALL.md +++ b/docs/HW_INSTALL.md @@ -5,7 +5,7 @@ To download and install NetAlertX on the hardware/server directly use the `curl` > [!NOTE] > This is an Experimental feature 🧪 and it relies on community support. > -> 🙏 Looking for maintainers for this installation method 🙂 Current community volunteers: +> 🙏 Looking for maintainers for this installation method 🙂 Current community volunteers: > - [slammingprogramming](https://github.com/slammingprogramming) > - [ingoratsdorf](https://github.com/ingoratsdorf) > @@ -13,8 +13,7 @@ To download and install NetAlertX on the hardware/server directly use the `curl` > Data loss is a possibility, **it is recommended to install NetAlertX using the supplied Docker image**. > [!WARNING] -> A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may -be dangerous, as you cannot see the code that's about to be executed on your system. +> A warning to the installation method below: Piping to bash is [controversial](https://pi-hole.net/2016/07/25/curling-and-piping-to-bash) and may be dangerous, as you cannot see the code that's about to be executed on your system. If you trust this repo, you can download the install script via one of the methods (curl/wget) below and it will fo its best to install NetAlertX on your system. @@ -40,7 +39,7 @@ Some facts about what and where something will be changed/installed by the HW in - Only tested to work on the system listed in the install directory. - **EXPERIMENTAL** and not recommended way to install NetAlertX. -> [!TIP] +> [!TIP] > If the below fails try grabbing and installing one of the [previous releases](https://github.com/jokob-sk/NetAlertX/releases) and run the installation from the zip package. These commands will download the `install.debian12.sh` script from the GitHub repository, make it executable with `chmod`, and then run it using `./install.debian12.sh`. @@ -81,7 +80,7 @@ wget https://raw.githubusercontent.com/jokob-sk/NetAlertX/main/install/ubuntu24/ > [!NOTE] > Use this on a clean LXC/VM for Debian 13 OR Ubuntu 24. -> The Scipt will detect OS and build acordingly. +> The Scipt will detect OS and build acordingly. > Maintained by [JVKeller](https://github.com/JVKeller) ### Installation via wget diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index fb112405..d1d08e1b 100755 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -218,7 +218,7 @@ services: ### 1.3 Migration from NetAlertX `v25.10.1` -Starting from v25.10.1, the container uses a [more secure, read-only runtime environment](./SECURITY_FEATURES.md), which requires all writable paths (e.g., logs, API cache, temporary data) to be mounted as `tmpfs` or permanent writable volumes, with sufficient access [permissions](./FILE_PERMISSIONS.md). +Starting from v25.10.1, the container uses a [more secure, read-only runtime environment](./SECURITY_FEATURES.md), which requires all writable paths (e.g., logs, API cache, temporary data) to be mounted as `tmpfs` or permanent writable volumes, with sufficient access [permissions](./FILE_PERMISSIONS.md). The data location has also hanged from `/app/db` and `/app/config` to `/data/db` and `/data/config`. See detailed steps below. #### STEPS: @@ -234,8 +234,8 @@ services: network_mode: "host" restart: unless-stopped volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db + - /local_data_dir/config:/app/config + - /local_data_dir/db:/app/db # (optional) useful for debugging if you have issues setting up the container - /local_data_dir/logs:/tmp/log environment: @@ -284,10 +284,8 @@ services: - NET_BIND_SERVICE # 🆕 New line restart: unless-stopped volumes: - - /local_data_dir/config:/data/config - - /local_data_dir/db:/data/db - # (optional) useful for debugging if you have issues setting up the container - #- /local_data_dir/logs:/tmp/log + - /local_data_dir/config:/data/config # 🆕 This has changed from /app to /data + - /local_data_dir/db:/data/db # 🆕 This has changed from /app to /data # Ensuring the timezone is the same as on the server - make sure also the TIMEZONE setting is configured - /etc/localtime:/etc/localtime:ro # 🆕 New line environment: diff --git a/docs/SESSION_INFO.md b/docs/SESSION_INFO.md index 757a9746..092b9288 100755 --- a/docs/SESSION_INFO.md +++ b/docs/SESSION_INFO.md @@ -1,62 +1,64 @@ -# Sessions Section in Device View +# Sessions Section – Device View -The **Sessions Section** provides details about a device's connection history. This data is automatically detected and cannot be edited by the user. +The **Sessions Section** shows a device’s connection history. All data is automatically detected and **cannot be edited**. - ![Session info](./img/SESSION_INFO/DeviceDetails_SessionInfo.png) +![Session info](./img/SESSION_INFO/DeviceDetails_SessionInfo.png) --- ## Key Fields -1. **Date and Time of First Connection** - - **Description:** Displays the first detected connection time for the device. - - **Editability:** Uneditable (auto-detected). - - **Source:** Automatically captured when the device is first added to the system. - -2. **Date and Time of Last Connection** - - **Description:** Shows the most recent time the device was online. - - **Editability:** Uneditable (auto-detected). - - **Source:** Updated with every new connection event. - -3. **Offline Devices with Missing or Conflicting Data** - - **Description:** Handles cases where a device is offline but has incomplete or conflicting session data (e.g., missing start times). - - **Handling:** The system flags these cases for review and attempts to infer missing details. +| Field | Description | Editable? | +| ------------------------------ | ------------------------------------------------------------------------------------------------ | --------------- | +| **First Connection** | The first time the device was detected on the network. | ❌ Auto-detected | +| **Last Connection** | The most recent time the device was online. | ❌ Auto-detected | --- -## How Sessions are Discovered and Calculated +## How Session Information Works ### 1. Detecting New Devices -When a device is first detected in the network, the system logs it in the events table: -`INSERT INTO Events (eve_MAC, eve_IP, eve_DateTime, eve_EventType, eve_AdditionalInfo, eve_PendingAlertEmail) SELECT cur_MAC, cur_IP, '{startTime}', 'New Device', cur_Vendor, 1 FROM CurrentScan WHERE NOT EXISTS (SELECT 1 FROM Devices WHERE devMac = cur_MAC)` +* New devices are automatically detected when they first appear on the network. +* A **New Device** record is created, capturing the MAC, IP, vendor, and detection time. -- Devices scanned in the current cycle (**CurrentScan**) are checked against the **Devices** table. -- If a device is new: - - A **New Device** event is logged. - - The device’s MAC, IP, vendor, and detection time are recorded. +### 2. Recording Connection Sessions -### 2. Logging Connection Sessions -When a new connection is detected, the system creates a session record: +* Every time a device connects, a session entry is created. +* Captured details include: -`INSERT INTO Sessions (ses_MAC, ses_IP, ses_EventTypeConnection, ses_DateTimeConnection, ses_EventTypeDisconnection, ses_DateTimeDisconnection, ses_StillConnected, ses_AdditionalInfo) SELECT cur_MAC, cur_IP, 'Connected', '{startTime}', NULL, NULL, 1, cur_Vendor FROM CurrentScan WHERE NOT EXISTS (SELECT 1 FROM Sessions WHERE ses_MAC = cur_MAC)` - -- A new session is logged in the **Sessions** table if no prior session exists. -- Fields like `MAC`, `IP`, `Connection Type`, and `Connection Time` are populated. -- The `Still Connected` flag is set to `1` (active connection). + * Connection type (wired or wireless) + * Connection time + * Device details (MAC, IP, vendor) ### 3. Handling Missing or Conflicting Data -- Devices with incomplete or conflicting session data (e.g., missing start times) are detected. -- The system flags these records and attempts corrections by inferring details from available data. + +* **Triggers:** + Devices are flagged when session data is incomplete, inconsistent, or conflicting. Examples include: + + * Missing first or last connection timestamps + * Overlapping session records + * Sessions showing a device as connected and disconnected at the same time + +* **System response:** + + * Automatically highlights affected devices in the **Sessions Section**. + * Attempts to **infer missing information** from available data, such as: + + * Estimating first or last connection times from nearby session events + * Correcting overlapping session periods + * Reconciling conflicting connection statuses + +* **User impact:** + + * Users do **not** need to manually fix session data. + * The system ensures the device’s connection history remains as accurate as possible for monitoring and reporting. ### 4. Updating Sessions -- When a device reconnects, its session is updated with a new connection timestamp. -- When a device disconnects: - - The **Disconnection Time** is recorded. - - The `Still Connected` flag is set to `0`. -The session information is then used to display the device presence under **Monitoring** -> **Presence**. +* **Reconnect:** Updates session with the new connection timestamp. +* **Disconnect:** Records disconnection time and marks the device as offline. + +This session information feeds directly into **Monitoring → Presence**, providing a live view of which devices are currently online. ![Monitoring Device Presence](./img/SESSION_INFO/Monitoring_Presence.png) - - diff --git a/docs/UPDATES.md b/docs/UPDATES.md index 2ac560d8..2d398dde 100755 --- a/docs/UPDATES.md +++ b/docs/UPDATES.md @@ -1,7 +1,8 @@ # Docker Update Strategies to upgrade NetAlertX -> [!WARNING] +> [!WARNING] > For versions prior to `v25.6.7` upgrade to version `v25.5.24` first (`docker pull ghcr.io/jokob-sk/netalertx:25.5.24`) as later versions don't support a full upgrade. Alternatively, devices and settings can be migrated manually, e.g. via [CSV import](./DEVICES_BULK_EDITING.md). +> See the [Migration guide](./MIGRATION.md) for details. This guide outlines approaches for updating Docker containers, usually when upgrading to a newer version of NetAlertX. Each method offers different benefits depending on the situation. Here are the methods: @@ -15,7 +16,7 @@ You can choose any approach that fits your workflow. > In the examples I assume that the container name is `netalertx` and the image name is `netalertx` as well. > [!NOTE] -> See also [Backup strategies](./BACKUPS.md) to be on the safe side. +> See also [Backup strategies](./BACKUPS.md) to be on the safe side. ## 1. Manual Updates @@ -48,7 +49,7 @@ sudo docker-compose up --pull always -d ## 2. Dockcheck for Bulk Container Updates -Always check the [Dockcheck](https://github.com/mag37/dockcheck) docs if encountering issues with the guide below. +Always check the [Dockcheck](https://github.com/mag37/dockcheck) docs if encountering issues with the guide below. Dockcheck is a useful tool if you have multiple containers to update and some flexibility for handling potential issues that might arise during mass updates. Dockcheck allows you to inspect each container and decide when to update. @@ -74,7 +75,7 @@ sudo ./dockcheck.sh ## 3. Automated Updates with Watchtower -Always check the [watchtower](https://github.com/containrrr/watchtower) docs if encountering issues with the guide below. +Always check the [watchtower](https://github.com/containrrr/watchtower) docs if encountering issues with the guide below. Watchtower monitors your Docker containers and automatically updates them when new images are available. This is ideal for ongoing updates without manual intervention. @@ -96,7 +97,7 @@ docker run -d \ --interval 300 # Check for updates every 5 minutes ``` -#### 3. Run Watchtower to update only NetAlertX: +#### 3. Run Watchtower to update only NetAlertX: You can specify which containers to monitor by listing them. For example, to monitor netalertx only: diff --git a/front/css/app.css b/front/css/app.css index 5d15b426..8c67112e 100755 --- a/front/css/app.css +++ b/front/css/app.css @@ -1,6 +1,6 @@ /* ----------------------------------------------------------------------------- # NetAlertX -# Open Source Network Guard / WIFI & LAN intrusion detector +# Open Source Network Guard / WIFI & LAN intrusion detector # # app.css - Front module. CSS styles #------------------------------------------------------------------------------- @@ -36,7 +36,7 @@ a[target="_blank"] { display: inline-block; /* Needed for positioning */ padding-right: 0.6em; /* Space for the icon */ } - + a[target="_blank"]::after { content: '↗'; position: absolute; @@ -55,7 +55,7 @@ a[target="_blank"] { right: -7px; top: 1px; } */ - + /* .select2-container--default .select2-selection--multiple .select2-selection__choice { padding-right: 15px !important; @@ -70,6 +70,11 @@ a[target="_blank"] { opacity: 1; } +[data-is-valid="0"] { + /* border: 1px solid red; */ + background-color: #ff4b4b; +} + /* ----------------------------------------------------------------------------- Helper Classes ----------------------------------------------------------------------------- */ @@ -100,7 +105,7 @@ a[target="_blank"] { background-color: black; font-family: 'Courier New', monospace; font-size: .85em; - + } .logs-row textarea { @@ -110,12 +115,12 @@ a[target="_blank"] { display:contents; position: relative; padding: 0.4em - + } #tab_Logging .actions .toggle{ - margin: 0.5em; + margin: 0.5em; height: 3em; } @@ -134,8 +139,8 @@ a[target="_blank"] { } .log-area { - padding: 3px; - width:100%; + padding: 3px; + width:100%; border-bottom-width: 1px; border-bottom-style: solid; border-color: #606060; @@ -246,7 +251,7 @@ a[target="_blank"] { { padding:8px; color: white; -} +} .header-status { @@ -262,7 +267,7 @@ a[target="_blank"] { position: absolute; top: 3px; margin-left: 15px; - display: none; + display: none; } @@ -298,9 +303,9 @@ body .NetAlertX-logo { - border-color:transparent !important; - height: 50px !important; - width: 50px !important; + border-color:transparent !important; + height: 50px !important; + width: 50px !important; margin-top:15px !important; border-radius: 1px !important; } @@ -327,7 +332,7 @@ body .content-wrapper, .right-side, .main-footer { - margin-left: 150px; + margin-left: 150px; } @@ -740,7 +745,7 @@ body text-decoration: underline; } -#ticker-message +#ticker-message { color:#FFFFFF; } @@ -774,7 +779,7 @@ body .file-checking .icon-wrap{ width: 200px; overflow: hidden; - text-overflow: ellipsis; + text-overflow: ellipsis; display: block; } @@ -788,7 +793,7 @@ body .file-checking .file-name-wrap{ overflow: hidden; - text-overflow: ellipsis; + text-overflow: ellipsis; display: flex; padding: 5px; } @@ -796,7 +801,7 @@ body .file-checking{ display: block; overflow: hidden; - text-overflow: ellipsis; + text-overflow: ellipsis; } @@ -854,16 +859,16 @@ body .db_tools_table_cell_a { display: table-cell; - text-align: center; - padding: 10px; - min-width: 180px; - width: 20%; + text-align: center; + padding: 10px; + min-width: 180px; + width: 20%; vertical-align: middle; } .db_tools_table_cell_b { display: table-cell; - text-align: justify; - font-size: 16px; + text-align: justify; + font-size: 16px; vertical-align: middle; padding: 10px; } @@ -876,12 +881,12 @@ height: 50px; } .nav-tabs-custom .tab-content { - background-color: white; - + background-color: white; + } @media (max-width: 767px) { - .nav-tabs-custom .tab-content { + .nav-tabs-custom .tab-content { overflow: scroll; } } @@ -898,7 +903,7 @@ height: 50px; font-size: 16px !important; } -.deviceSelector +.deviceSelector { display: block; } @@ -935,7 +940,7 @@ height: 50px; height: 10px; display: inline-block; /* background: #fff; */ - opacity: .75; + opacity: .75; } /* --------------------------------------------------------- */ @@ -979,32 +984,32 @@ height: 50px; } /* .setting_input{ width:70%; - + } .setting_name { - width:30%; + width:30%; } */ } @media (min-width: 768px) { -.setting_description { +.setting_description { /* color: green; */ display: block; } /* .setting_input{ - width:40%; + width:40%; } .setting_name { - width:19%; + width:19%; } */ } /* Hide unusable buttons on the settings page for the NEWDEV plugin*/ -#settingsPage #add_option_NEWDEV_devGroup, -#settingsPage #add_option_NEWDEV_devLocation, +#settingsPage #add_option_NEWDEV_devGroup, +#settingsPage #add_option_NEWDEV_devLocation, #settingsPage #add_option_NEWDEV_devOwner, #settingsPage #copy_icons_NEWDEV_devIcon, #settingsPage #add_icon_NEWDEV_devIcon, @@ -1024,11 +1029,11 @@ height: 50px; #settingsPage .small-box .inner .card-title { overflow: hidden; - text-overflow: ellipsis; + text-overflow: ellipsis; white-space: nowrap; color: white; } - + .settingswrap { @@ -1048,13 +1053,13 @@ height: 50px; .padding-bottom { padding-bottom: 100px; -} +} .settings-group -{ +{ font-size: 20px; padding-top: 7px; - padding-bottom: 9px; + padding-bottom: 9px; } .overview-section .small-box .icon @@ -1069,7 +1074,7 @@ height: 50px; } .overview-group -{ +{ font-size: 20px; padding-top: 7px; padding-bottom: 9px; @@ -1082,8 +1087,8 @@ height: 50px; } -#settingsPage .table_row { - padding: 3px; +#settingsPage .table_row { + padding: 3px; /* width:100%; */ /* display: flex; */ border-bottom-width: 1px; @@ -1102,7 +1107,7 @@ height: 50px; .setting_name { /* width:19%; */ - font-weight: 300; + font-weight: 300; } @@ -1111,24 +1116,24 @@ height: 50px; display:none !important; } -.center +.center { margin: 0; - position: relative; + position: relative; left: 50%; -ms-transform: translate(-50%, -50%); transform: translate(-50%, -50%); } -.top-margin +.top-margin { margin-top: 50px; } /* Settings */ -#settingsPage .overview-setting-value{ - display:unset; +#settingsPage .overview-setting-value{ + display:unset; } @@ -1165,7 +1170,7 @@ height: 50px; } .text-overflow-hidden -{ +{ overflow: hidden; text-overflow: clip; } @@ -1175,9 +1180,9 @@ height: 50px; padding: 10px; /* background-color: #272c30; */ margin: 10px; - + } -#settingsPage .panel-heading:hover{ +#settingsPage .panel-heading:hover{ background-color: #272c30; } @@ -1185,12 +1190,12 @@ height: 50px; font-size: medium; /* background-color: #272c30; */ margin: 10px; - + } -.settings_content input[type=checkbox] -{ - width: auto +.settings_content input[type=checkbox] +{ + width: auto } .override{ @@ -1212,7 +1217,7 @@ height: 50px; input[readonly] { /* Apply styles to the readonly input */ background-color: #646566 !important; - color: #e6e6e6; + color: #e6e6e6; cursor: not-allowed; } @@ -1300,7 +1305,7 @@ input[readonly] { /* margin-bottom:20px; */ } -#settingsPage .select2-selection +#settingsPage .select2-selection { width: initial; display: inline-block; @@ -1314,8 +1319,8 @@ input[readonly] { #settingsPage .select2-selection { background-color: rgb(96, 96, 96); -} -#settingsPage .select2-container +} +#settingsPage .select2-container { width: 100% !important; } @@ -1398,7 +1403,7 @@ input[readonly] { backdrop-filter: brightness(50%); } -.iconPreviewSelector +.iconPreviewSelector { text-align: center; padding: 15px; @@ -1440,7 +1445,7 @@ input[readonly] { } -.dummyDevice +.dummyDevice { text-align: end; } @@ -1461,7 +1466,7 @@ input[readonly] { } .info-icon-nav -{ +{ top: -6px; position: absolute; z-index: 1; @@ -1538,7 +1543,7 @@ input[readonly] { } #panDetails .input-group { - + min-height: 40px; } @@ -1583,7 +1588,7 @@ input[readonly] { } .devicePropAction -{ +{ width: 1.2em; height: 1.2em; display: inline-block; @@ -1593,11 +1598,11 @@ input[readonly] { } .devicePropAction:hover -{ +{ font-size: larger; padding: 0em; margin: 0em; - + } @@ -1607,7 +1612,7 @@ input[readonly] { display: block; float:inline-end; height: 2em; -} +} #panDetails .dataTables_wrapper .bottom .dataTables_info { @@ -1636,22 +1641,22 @@ input[readonly] { height: 14px; } -#deviceDetailsEdit .select2-container--default .select2-selection--multiple .select2-selection__choice +#deviceDetailsEdit .select2-container--default .select2-selection--multiple .select2-selection__choice { height: 20px; } -#deviceDetailsEdit .select2-container--disabled +#deviceDetailsEdit .select2-container--disabled { - background-color: #606060; + background-color: #606060; } -#deviceDetailsEdit .select2-container--default .select2-selection--multiple .select2-selection__choice span +#deviceDetailsEdit .select2-container--default .select2-selection--multiple .select2-selection__choice span { font-size: 14px; } -#deviceDetailsEdit .select2-selection +#deviceDetailsEdit .select2-selection { width: initial; display: inline-block; @@ -1681,7 +1686,7 @@ input[readonly] { font-size: 14px; } .custom-badge -{ +{ border: 1px solid #aaa; border-radius: 4px; border-style: solid; @@ -1716,7 +1721,7 @@ input[readonly] { } -#deviceDetailsEdit .select2-container +#deviceDetailsEdit .select2-container { width: 100% !important; } @@ -1799,7 +1804,7 @@ input[readonly] { z-index: 5; } #networkTree .netNodeText -{ +{ position: absolute; } #networkTree .netPort @@ -1812,7 +1817,7 @@ input[readonly] { #networkTree .portBckgIcon { opacity: 0.3; - display: initial; + display: initial; float: left; width: 1em; } @@ -1822,7 +1827,7 @@ input[readonly] { margin-left: 16px; /* border: solid; border-color:#606060; */ - position: relative; + position: relative; } #networkTree .netIcon { @@ -1850,8 +1855,8 @@ input[readonly] { } #hover-box .devName -{ - font-size: larger; +{ + font-size: larger; display: contents; } @@ -1910,7 +1915,7 @@ input[readonly] { #networkTree .highlightedNode { /* border: solid; */ - border-color:var(--color-lightblue); + border-color:var(--color-lightblue); box-shadow: var(--color-lightblue) 0px 0px 20px; } @@ -1968,7 +1973,7 @@ input[readonly] { } .sort-btn { - + right: 5px; top: 50%; transform: translateY(-50%); @@ -2020,7 +2025,7 @@ input[readonly] { } .plugin-filters -{ +{ margin: 7px; margin-right: 7px; margin-bottom: 9px; @@ -2054,7 +2059,7 @@ input[readonly] { } .plugin-content #tabs-content-location -{ +{ margin: 0px; padding-top: 0; } @@ -2066,7 +2071,7 @@ input[readonly] { } .plugin-content .tab-content -{ +{ padding-top: 10px; } @@ -2103,7 +2108,7 @@ input[readonly] { @media (max-width: 500px) { .header-server-time { - display: none; + display: none; } } @@ -2234,12 +2239,12 @@ input[readonly] { display: grid; } -#workflowContainerWrap .panel-collapse +#workflowContainerWrap .panel-collapse { padding: 5px; } -.workflows +.workflows { max-width: 800px; } @@ -2285,7 +2290,7 @@ input[readonly] { color: #000; } -.workflows .button-container +.workflows .button-container { /* display: contents; */ text-align: center; @@ -2305,7 +2310,7 @@ input[readonly] { margin: 5px; } -.workflows .button-container +.workflows .button-container { padding-right: 0px !important; padding-left: 0px !important; @@ -2318,19 +2323,19 @@ input[readonly] { /* .button-container button { - width:100%; + width:100%; } */ .red-hover-text:hover { - color: var(--color-red) !important; + color: var(--color-red) !important; } .green-hover-text:hover { color: var(--color-green) !important; } - + .workflows .bckg-icon-1-line { font-size: 3em; @@ -2362,7 +2367,7 @@ input[readonly] { z-index: 1; } -.workflows .workflow-card +.workflows .workflow-card { display: block; } @@ -2372,7 +2377,7 @@ input[readonly] { padding: 10px; } -.workflow-card, .actions-list +.workflow-card, .actions-list { display: contents; padding: 5px; @@ -2384,7 +2389,7 @@ input[readonly] { z-index:1; } -.condition +.condition { padding: 5px; padding-left: 10px; diff --git a/front/js/modal.js b/front/js/modal.js index 54073067..dbcf5e10 100755 --- a/front/js/modal.js +++ b/front/js/modal.js @@ -96,7 +96,7 @@ function showModalInput( btnOK = getString("Gen_Okay"), callbackFunction = null, triggeredBy = null, - defaultValue = "" + defaultValue = "" ) { prefix = "modal-input"; @@ -121,7 +121,7 @@ function showModalInput( setTimeout(function () { $(`#${prefix}-textarea`).focus(); }, 500); - + } // ----------------------------------------------------------------------------- @@ -143,7 +143,7 @@ function showModalFieldInput( $(`#${prefix}-OK`).html(btnOK); if (callbackFunction != null) { - + modalCallbackFunction = callbackFunction; } @@ -181,11 +181,11 @@ function showModalPopupForm( $(`#${prefix}-cancel`).html(btnCancel); $(`#${prefix}-OK`).html(btnOK); - // if curValue not null + // if curValue not null if (curValue) { - initialValues = JSON.parse(atob(curValue)); + initialValues = JSON.parse(atob(curValue)); } outputHtml = ""; @@ -193,7 +193,7 @@ function showModalPopupForm( if (Array.isArray(popupFormJson)) { popupFormJson.forEach((field, index) => { // You'll need to define these or map them from `field` - const setKey = field.function || `field_${index}`; + const setKey = field.function || `field_${index}`; const setName = getString(`${parentSettingKey}_popupform_${setKey}_name`); const labelClasses = "col-sm-2"; // example, or from your obj.labelClasses const inputClasses = "col-sm-10"; // example, or from your obj.inputClasses @@ -207,9 +207,9 @@ function showModalPopupForm( } } - const fieldOptionsOverride = field.type?.elements[0]?.elementOptions || []; + const fieldOptionsOverride = field.type?.elements[0]?.elementOptions || []; const setValue = initialValue; - const setType = JSON.stringify(field.type); + const setType = JSON.stringify(field.type); const setEvents = field.events || []; // default to empty array if missing const setObj = { setKey, setValue, setType, setEvents }; @@ -218,17 +218,17 @@ function showModalPopupForm(
${generateFormHtml( null, // settingsData only required for datatables - setObj, - null, - fieldOptionsOverride, + setObj, + null, + fieldOptionsOverride, null )}
@@ -239,7 +239,7 @@ function showModalPopupForm( outputHtml += inputFormHtml; }); } - + $(`#modal-form-plc`).html(outputHtml); // Bind OK button click event @@ -247,12 +247,19 @@ function showModalPopupForm( let settingsArray = []; if (Array.isArray(popupFormJson)) { popupFormJson.forEach(field => { - collectSetting( + const result = collectSetting( `${parentSettingKey}_popupform`, // prefix field.function, // setCodeName field.type, // setType (object) settingsArray ); + settingsArray = result.settingsArray; + + if (!result.dataIsValid) { + msg = getString("Gen_Invalid_Value") + ":" + result.failedSettingKey; + console.error(msg); + showModalOk("ERROR", msg); + } }); } @@ -276,7 +283,7 @@ function showModalPopupForm( const newOption = $("") .attr("value", encodedValue) .text(label); - + $("#" + selectId).append(newOption); initListInteractionOptions(newOption); } @@ -429,10 +436,10 @@ function safeDecodeURIComponent(content) { return content; // Return the original content if decoding fails } } - + // ----------------------------------------------------------------------------- -// Backend notification Polling +// Backend notification Polling // ----------------------------------------------------------------------------- // Function to check for notifications function checkNotification() { @@ -440,7 +447,7 @@ function checkNotification() { const phpEndpoint = 'php/server/utilNotification.php'; $.ajax({ - url: notificationEndpoint, + url: notificationEndpoint, type: 'GET', success: function(response) { // console.log(response); @@ -492,7 +499,7 @@ function checkNotification() { }, error: function() { console.warn(`🟥 Error checking ${notificationEndpoint}`) - + } }); } @@ -582,7 +589,7 @@ const phpEndpoint = 'php/server/utilNotification.php'; // -------------------------------------------------- // Write a notification -function write_notification(content, level) { +function write_notification(content, level) { $.ajax({ url: phpEndpoint, // Change this to the path of your PHP script @@ -603,8 +610,8 @@ function write_notification(content, level) { // -------------------------------------------------- // Write a notification -function markNotificationAsRead(guid) { - +function markNotificationAsRead(guid) { + $.ajax({ url: phpEndpoint, type: 'GET', @@ -628,8 +635,8 @@ function markNotificationAsRead(guid) { // -------------------------------------------------- // Remove a notification -function removeNotification(guid) { - +function removeNotification(guid) { + $.ajax({ url: phpEndpoint, type: 'GET', diff --git a/front/js/settings_utils.js b/front/js/settings_utils.js index c0056a66..b567c532 100755 --- a/front/js/settings_utils.js +++ b/front/js/settings_utils.js @@ -71,7 +71,7 @@ function getPluginConfig(pluginsData, prefix) { // Show the description of a setting function showDescriptionPopup(e) { - console.log($(e).attr("my-set-key")); + console.log($(e).attr("my-set-key")); showModalOK("Info", getString($(e).attr("my-set-key") + '_description')) } @@ -92,13 +92,13 @@ function pluginCards(prefixesOfEnabledPlugins, includeSettings) { prefix + "_" + set }"> ${getSetting(prefix + "_" + set)} -
+ `; }); - html += ` + html += `
@@ -110,10 +110,10 @@ function pluginCards(prefixesOfEnabledPlugins, includeSettings) { ${includeSettings_html}
-
${getString(prefix + "_icon")}
- +
${getString(prefix + "_icon")}
+
- +
`; }); @@ -251,17 +251,17 @@ function settingsCollectedCorrectly(settingsArray, settingsJSON_DB) { function cloneDataTableRow(el){ console.log(el); - + const id = "NEWDEV_devCustomProps_table"; // Your table ID const table = $('#'+id).DataTable(); - + // Get the 'my-index' attribute from the closest tr element const myIndex = parseInt($(el).closest("tr").attr("my-index")); // Find the row in the table with the matching 'my-index' const row = table.rows().nodes().to$().filter(`[my-index="${myIndex}"]`).first().get(0); - + // Clone the row (including its data and controls) let clonedRow = $(row).clone(true, true); // The true arguments copy the data and event handlers @@ -270,7 +270,7 @@ function cloneDataTableRow(el){ console.log(clonedRow); - + // Add the cloned row to the DataTable table.row.add(clonedRow[0]).draw(); @@ -291,13 +291,13 @@ function removeDataTableRow(el) { // Find the row in the table with the matching 'my-index' const row = table.rows().nodes().to$().filter(`[my-index="${myIndex}"]`).first().get(0); - + // Remove the row from the DataTable table.row(row).remove().draw(); } else { - showMessage (getString("CustProps_cant_remove"), 3000, "modal_red"); + showMessage (getString("CustProps_cant_remove"), 3000, "modal_red"); } } @@ -308,9 +308,9 @@ function addViaPopupForm(element) { const toId = $(element).attr("my-input-to"); const curValue = $(`#${toId}`).val(); - const parsed = JSON.parse(atob($(`#${toId}`).data("elementoptionsbase64"))); + const parsed = JSON.parse(atob($(`#${toId}`).data("elementoptionsbase64"))); const popupFormJson = parsed.find(obj => "popupForm" in obj)?.popupForm ?? null; - + console.log(`toId | curValue: ${toId} | ${curValue}`); showModalPopupForm( @@ -393,7 +393,7 @@ function selectAll(element) { settingsChanged(); var selectElement = $(`#${$(element).attr("my-input-to")}`); - + // Iterate over each option within the select element selectElement.find('option').each(function() { // Mark each option as selected @@ -409,13 +409,13 @@ function selectAll(element) { function unselectAll(element) { settingsChanged(); var selectElement = $(`#${$(element).attr("my-input-to")}`); - + // Iterate over each option within the select element selectElement.find('option').each(function() { // Unselect each option $(this).prop('selected', false); }); - + // Trigger the 'change' event to notify Bootstrap Select of the changes selectElement.trigger('change'); } @@ -426,7 +426,7 @@ function selectChange(element) { settingsChanged(); var selectElement = $(`#${$(element).attr("my-input-to")}`); - + selectElement.parent().find("input").focus().click(); } @@ -464,9 +464,9 @@ function initListInteractionOptions(element) { // Parent has my-transformers="name|base64" const toId = $parent.attr("id"); const curValue = $option.val(); - const parsed = JSON.parse(atob($parent.data("elementoptionsbase64"))); + const parsed = JSON.parse(atob($parent.data("elementoptionsbase64"))); const popupFormJson = parsed.find(obj => "popupForm" in obj)?.popupForm ?? null; - + showModalPopupForm( ` ${getString("Gen_Update_Value")}`, // title "", // message @@ -515,8 +515,8 @@ function filterRows(inputText) { var $panelHeader = $panel.find('.panel-heading'); var $panelBody = $panel.find('.panel-collapse'); - $panel.show() - $panelHeader.show() + $panel.show() + $panelHeader.show() $panelBody.collapse('show'); $panelBody.find(".table_row:not(.docs)").each(function () { @@ -525,11 +525,11 @@ function filterRows(inputText) { var isMetadataRow = rowId && rowId.endsWith("__metadata"); if (!isMetadataRow) { $row.show() - } + } }); - + }); - + } else{ // filter @@ -537,25 +537,25 @@ function filterRows(inputText) { var $panel = $(this); var $panelHeader = $panel.find('.panel-heading'); var $panelBody = $panel.find('.panel-collapse'); - + var anyVisible = false; // Flag to check if any row is visible - + $panelBody.find(".table_row:not(.docs)").each(function () { var $row = $(this); - + // Check if the row ID ends with "__metadata" var rowId = $row.attr("id"); var isMetadataRow = rowId && rowId.endsWith("__metadata"); - + // Always hide metadata rows if (isMetadataRow) { $row.hide(); return; // Skip further processing for metadata rows } - + var description = $row.find(".setting_description").text().toLowerCase(); var setKey = $row.find(".setting_name code").text().toLowerCase(); - + if ( description.includes(inputText.toLowerCase()) || setKey.includes(inputText.toLowerCase()) @@ -566,7 +566,7 @@ function filterRows(inputText) { $row.hide(); } }); - + // Determine whether to hide or show the panel based on visibility of rows if (anyVisible) { $panelBody.collapse('show'); // Ensure the panel body is shown if there are visible rows @@ -582,7 +582,7 @@ function filterRows(inputText) { } - + } @@ -661,7 +661,7 @@ function generateOptionsOrSetOptions( processDataCallback, // Callback function to generate entries based on options targetField, // Target field or element where selected value should be applied or updated transformers = [], // Transformers to be applied to the values - overrideOptions = null // override options if available + overrideOptions = null // override options if available ) { // console.log(setKey); @@ -712,7 +712,7 @@ function applyTransformers(val, transformers) { break; case "getString": // no change - val = val; + val = val; break; default: console.warn(`Unknown transformer: ${transformer}`); @@ -745,13 +745,13 @@ function reverseTransformers(val, transformers) { break; case "getString": // retrieve string - val = getString(val); + val = getString(val); break; case "deviceChip": - mac = val // value is mac + mac = val // value is mac val = `${getDevDataByMac(mac, "devName")}` break; - case "deviceRelType": + case "deviceRelType": val = val; // nothing to do break; default: @@ -779,10 +779,11 @@ const handleElementOptions = (setKey, elementOptions, transformers, val) => { let getStringKey = ""; let onClick = "console.log('onClick - Not implemented');"; let onChange = "console.log('onChange - Not implemented');"; + let focusout = "console.log('focusout - Not implemented');"; let customParams = ""; let customId = ""; let columns = []; - let base64Regex = ""; + let base64Regex = ""; let elementOptionsBase64 = btoa(JSON.stringify(elementOptions)); elementOptions.forEach((option) => { @@ -830,6 +831,9 @@ const handleElementOptions = (setKey, elementOptions, transformers, val) => { if (option.onChange) { onChange = option.onChange; } + if (option.focusout) { + focusout = option.focusout; + } if (option.customParams) { customParams = option.customParams; } @@ -867,7 +871,8 @@ const handleElementOptions = (setKey, elementOptions, transformers, val) => { customId, columns, base64Regex, - elementOptionsBase64 + elementOptionsBase64, + focusout }; }; @@ -877,7 +882,7 @@ const handleElementOptions = (setKey, elementOptions, transformers, val) => { // ----------------------------------------------------------------------------- // -------------------------------------------------- -// Creates an object from an array +// Creates an object from an array function arrayToObject(array) { const obj = []; array.forEach((item, index) => { @@ -895,18 +900,18 @@ function generateOptions(options, valuesArray, targetField, transformers, placeh resultArray = [] selectedArray = [] - cssClass = "" + cssClass = "" // determine if options or values are used in the listing if (valuesArray.length > 0 && options.length > 0){ - // multiselect list -> options only + selected the ones in valuesArray + // multiselect list -> options only + selected the ones in valuesArray resultArray = options; selectedArray = valuesArray } else if (valuesArray.length > 0 && options.length == 0){ - // editable list -> values only + // editable list -> values only resultArray = arrayToObject(valuesArray) cssClass = "interactable-option" // generates [1x 📝 | 2x 🚮] } else if (options.length > 0){ @@ -914,7 +919,7 @@ function generateOptions(options, valuesArray, targetField, transformers, placeh // dropdown -> options only (value == 1 STRING not ARRAY) resultArray = options; } - + // Create a map to track the index of each item in valuesArray const orderMap = new Map(valuesArray.map((item, index) => [item, index])); @@ -961,7 +966,7 @@ function generateList(options, valuesArray, targetField, transformers, placehold listHtml += `
  • ${labelName}
    • `; }); - + // Place the resulting HTML into the specified placeholder div $("#" + placeholder).replaceWith(listHtml); } @@ -972,7 +977,7 @@ function genListWithInputSet(options, valuesArray, targetField, transformers, pl var listHtml = ""; - + options.forEach(function(item) { let selected = valuesArray.includes(item.id) ? 'selected' : ''; @@ -988,9 +993,9 @@ function genListWithInputSet(options, valuesArray, targetField, transformers, pl } listHtml += `
  • - ${labelName} + ${labelName}
    • `; - + }); // Place the resulting HTML into the specified placeholder div @@ -1001,8 +1006,8 @@ function genListWithInputSet(options, valuesArray, targetField, transformers, pl // Collects a setting based on code name function collectSetting(prefix, setCodeName, setType, settingsArray) { // Parse setType if it's a JSON string - const setTypeObject = (typeof setType === "string") - ? JSON.parse(processQuotes(setType)) + const setTypeObject = (typeof setType === "string") + ? JSON.parse(processQuotes(setType)) : setType; const dataType = setTypeObject.dataType; @@ -1015,6 +1020,20 @@ function collectSetting(prefix, setCodeName, setType, settingsArray) { const { elementType, elementOptions = [], transformers = [] } = elementWithInputValue; + // Check if validation failed + if ( + $(`#${setCodeName}`) + && $(`#${setCodeName}`).attr("data-is-valid") + && $(`#${setCodeName}`).attr("data-is-valid") == 0 + ) + { + return { + "settingsArray": settingsArray, + "dataIsValid": false, + "failedSettingKey": setCodeName + }; + } + const opts = handleElementOptions('none', elementOptions, transformers, val = ""); // Map of handlers @@ -1038,7 +1057,7 @@ function collectSetting(prefix, setCodeName, setType, settingsArray) { let temps = []; if (opts.isOrdeable) { temps = $(`#${setCodeName}`).val(); - } else { + } else { const sel = $(`#${setCodeName}`).attr("my-editable") === "true" ? "" : ":selected"; $(`#${setCodeName} option${sel}`).each(function() { const vl = $(this).val(); @@ -1066,7 +1085,7 @@ function collectSetting(prefix, setCodeName, setType, settingsArray) { let handlerKey; if (dataType === "string" && elementType === "datatable") { handlerKey = "datatableString"; - } else if (dataType === "string" || + } else if (dataType === "string" || (dataType === "integer" && (opts.inputType === "number" || opts.inputType === "text"))) { handlerKey = "simpleValue"; } else if (opts.inputType === "checkbox") { @@ -1084,7 +1103,11 @@ function collectSetting(prefix, setCodeName, setType, settingsArray) { const value = handlers[handlerKey](); settingsArray.push([prefix, setCodeName, dataType, value]); - return settingsArray; + return { + "settingsArray": settingsArray, + "dataIsValid": true, + "failedSettingKey": "" + }; } @@ -1093,22 +1116,22 @@ function collectSetting(prefix, setCodeName, setType, settingsArray) { function generateFormHtml(settingsData, set, overrideValue, overrideOptions, originalSetKey) { let inputHtml = ''; - isEmpty(overrideValue) ? inVal = set['setValue'] : inVal = overrideValue; + isEmpty(overrideValue) ? inVal = set['setValue'] : inVal = overrideValue; const setKey = set['setKey']; const setType = set['setType']; // if (setKey == '') { - + // console.log(setType); // console.log(setKey); // console.log(overrideValue); - // console.log(inVal); + // console.log(inVal); // } // Parse the setType JSON string // console.log(processQuotes(setType)); - + const setTypeObject = JSON.parse(processQuotes(setType)) const dataType = setTypeObject.dataType; const elements = setTypeObject.elements || []; @@ -1137,20 +1160,21 @@ function generateFormHtml(settingsData, set, overrideValue, overrideOptions, ori customId, columns, base64Regex, - elementOptionsBase64 + elementOptionsBase64, + focusout } = handleElementOptions(setKey, elementOptions, transformers, inVal); // Override value let val = valRes; // if (setKey == '') { - + // console.log(setType); // console.log(setKey); // console.log(overrideValue); - // console.log(inVal); - // console.log(val); - + // console.log(inVal); + // console.log(val); + // } // Generate HTML based on elementType @@ -1159,16 +1183,17 @@ function generateFormHtml(settingsData, set, overrideValue, overrideOptions, ori const multi = isMultiSelect ? "multiple" : ""; const addCss = isOrdeable ? "select2 select2-hidden-accessible" : ""; - inputHtml += ``; break; case 'button': - inputHtml += `