From b9ef9ad04182acc3f8a82c9cf787488870ef1c02 Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Wed, 26 Nov 2025 09:25:37 +1100 Subject: [PATCH] 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