DOCS: SYNOLOGY permissions guide #1310

Signed-off-by: jokob-sk <jokob.sk@gmail.com>

docs/COMMON_ISSUES.md

@@ -112,3 +112,11 @@ Slowness can be caused by:
 
 > See [Performance Tips](./PERFORMANCE.md) for detailed optimization steps.
 
+
+#### IP flipping
+
+With `ARPSCAN` scans some devices might flip IP addresses after each scan triggering false notifications. This is because some devices respond to broadcast calls and thus different IPs after scans are logged.
+
+See how to prevent IP flipping in the [ARPSCAN plugin guide](/front/plugins/arp_scan/README.md).
+
+Alternatively adjust your [notification settings](./NOTIFICATIONS.md) to prevent false positives by filtering out events or devices.

docs/DOCKER_INSTALLATION.md

@@ -61,20 +61,38 @@ See alternative [docked-compose examples](https://github.com/jokob-sk/NetAlertX/
 
 | Required | Path | Description |
 | :------------- | :------------- | :-------------|
-| ✅ | `:/data` | Folder which will contain the `/db/app.db`, `/config/app.conf` & `/config/devices.csv` ([read about devices.csv](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DEVICES_BULK_EDITING.md)) files  |
-| ✅ | `/etc/localtime:/etc/localtime:ro` | Ensuring the timezone is teh same as on teh server.  |
+| ✅ | `:/data` | Folder which needs to contain a `/db` and `/config` sub-folders. |
+| ✅ | `/etc/localtime:/etc/localtime:ro` | Ensuring the timezone is the same as on the server.  |
 | | `:/tmp/log` |  Logs folder useful for debugging if you have issues setting up the container  |
 | | `:/tmp/api` |  The [API endpoint](https://github.com/jokob-sk/NetAlertX/blob/main/docs/API.md) containing static (but regularly updated) json and other files. Path configurable via `NETALERTX_API` environment variable.   |
 | | `:/app/front/plugins/<plugin>/ignore_plugin` | Map a file `ignore_plugin` to ignore a plugin. Plugins can be soft-disabled via settings. More in the [Plugin docs](https://github.com/jokob-sk/NetAlertX/blob/main/docs/PLUGINS.md).  |
 | | `:/etc/resolv.conf` | Use a custom `resolv.conf` file for [better name resolution](https://github.com/jokob-sk/NetAlertX/blob/main/docs/REVERSE_DNS.md).  |
 
-> Use separate `db` and `config` directories, do not nest them.
+### Folder structure
+
+Use separate `db` and `config` directories, do not nest them:
+
+```
+data
+├── config
+└── db
+```
+
+### Permissions
+
+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
+```
 
 ### 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
 
+
 #### 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.

docs/MIGRATION.md

@@ -278,8 +278,9 @@ Run the container with the `--user "0"` parameter. Please note, some systems wil
 
 ```sh
 docker run -it --rm --name netalertx --user "0" \
-  -v /local_data_dir/config:/data/config \
-  -v /local_data_dir/db:/data/db \
+  -v /local_data_dir/config:/app/config \
+  -v /local_data_dir/db:/app/db \
+  -v /local_data_dir:/data \
   --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
   ghcr.io/jokob-sk/netalertx:latest
 ```

docs/PIHOLE_GUIDE.md

@@ -1,8 +1,29 @@
 # Integration with PiHole
 
-NetAlertX comes with 2 plugins suitable for integrating with your existing PiHole instance. One plugin is using a direct SQLite DB connection, the other leverages the DHCP.leases file generated by PiHole. You can combine both approaches and also supplement it with other [plugins](/docs/PLUGINS.md). 
+NetAlertX comes with 3 plugins suitable for integrating with your existing PiHole instance. The first plugin uses the v6 API, the second plugin is using a direct SQLite DB connection, the other leverages the `DHCP.leases` file generated by PiHole. You can combine multiple approaches and also supplement scans with other [plugins](/docs/PLUGINS.md).
 
-## Approach 1: `DHCPLSS` Plugin - Import devices from the PiHole DHCP leases file
+## Approach 1: `PIHOLEAPI` Plugin - Import devices directly from PiHole v6 API
+
+![PIHOLEAPI sample settings](./img/PIHOLE_GUIDE/PIHOLEAPI_settings.png)
+
+To use this approach make sure the Web UI password in **Pi-hole** is set.
+
+| Setting | Description | Recommended value |
+| :------------- | :------------- | :-------------|
+| `PIHOLEAPI_URL` | Your Pi-hole base URL including port.  | `http://192.168.1.82:9880/` |
+| `PIHOLEAPI_RUN_SCHD` | If you run multiple device scanner plugins, align the schedules of all plugins to the same value.  | `*/5 * * * *` |
+| `PIHOLEAPI_PASSWORD` | The Web UI base64 encoded (en-/decoding handled by the app) admin password. | `passw0rd` |
+| `PIHOLEAPI_SSL_VERIFY` | Whether to verify HTTPS certificates. Disable only for self-signed certificates. | `False` |
+| `PIHOLEAPI_API_MAXCLIENTS` | Maximum number of devices to request from Pi-hole. Defaults are usually fine. | `500` |
+| `PIHOLEAPI_FAKE_MAC` | Generate FAKE MAC from IP. | `False` |
+
+Check the [PiHole API plugin readme](https://github.com/jokob-sk/NetAlertX/tree/main/front/plugins/pihole_api_scan/) for details and troubleshooting.
+
+### docker-compose changes
+
+No changes needed
+
+## Approach 2: `DHCPLSS` Plugin - Import devices from the PiHole DHCP leases file
 
 ![DHCPLSS sample settings](./img/PIHOLE_GUIDE/DHCPLSS_pihole_settings.png)
 
@@ -23,7 +44,7 @@ Check the [DHCPLSS plugin readme](https://github.com/jokob-sk/NetAlertX/tree/mai
 | `:/etc/pihole/dhcp.leases` |  PiHole's `dhcp.leases` file. Required if you want to use PiHole `dhcp.leases` file. This has to be matched with a corresponding `DHCPLSS_paths_to_check` setting entry (the path in the container must contain `pihole`) |
 
 
-## Approach 2: `PIHOLE` Plugin - Import devices directly from the PiHole database
+## Approach 3: `PIHOLE` Plugin - Import devices directly from the PiHole database
 
 ![DHCPLSS sample settings](./img/PIHOLE_GUIDE/PIHOLE_settings.png)
 

docs/REVERSE_DNS.md

@@ -53,7 +53,6 @@ You can configure a custom **/etc/resolv.conf** file in **docker-compose.yml** a
 #### docker-compose.yml:
 
 ```yaml
-version: "3"
 services:
   netalertx:
     container_name: netalertx

docs/SYNOLOGY_GUIDE.md

@@ -9,21 +9,23 @@ The folders you are creating below will contain the configuration and the databa
 1. Create a parent folder named `netalertx`
 2. Create a `db` sub-folder
 
-![Folder structure](./img/SYNOLOGY/01_Create_folder_structure.png)
-![Folder structure](./img/SYNOLOGY/02_Create_folder_structure_db.png)
-![Folder structure](./img/SYNOLOGY/03_Create_folder_structure_db.png)
+  ![Folder structure](./img/SYNOLOGY/01_Create_folder_structure.png)
+  ![Folder structure](./img/SYNOLOGY/02_Create_folder_structure_db.png)
+  ![Folder structure](./img/SYNOLOGY/03_Create_folder_structure_db.png)
 
 3. Create a `config` sub-folder
 
-![Folder structure](./img/SYNOLOGY/04_Create_folder_structure_config.png)
+  ![Folder structure](./img/SYNOLOGY/04_Create_folder_structure_config.png)
 
 4. Note down the folders Locations:
 
-![Getting the location](./img/SYNOLOGY/05_Access_folder_properties.png)
-![Getting the location](./img/SYNOLOGY/06_Note_location.png)
+  ![Getting the location](./img/SYNOLOGY/05_Access_folder_properties.png)
+  ![Getting the location](./img/SYNOLOGY/06_Note_location.png)
 
-5. Open **Container manager** -> **Project** and click **Create**.
-6. Fill in the details:
+## Creating the Project
+
+1. Open **Container manager** -> **Project** and click **Create**.
+2. Fill in the details:
 
 - Project name: `netalertx`
 - Path: `/app_storage/netalertx` (will differ from yours)
@@ -31,7 +33,6 @@ The folders you are creating below will contain the configuration and the databa
 
 
 ```yaml
-version: "3"
 services:
   netalertx:
     container_name: netalertx
@@ -57,27 +58,32 @@ services:
       - PORT=20211
 ```
 
-![Project settings](./img/SYNOLOGY/07_Create_project.png)
+  ![Project settings](./img/SYNOLOGY/07_Create_project.png)
 
-7. Replace the paths to your volume and comment out unnecessary line(s):
+3. Replace the paths to your volume and comment out unnecessary line(s):
 
-- This is only an example, your paths will differ.
+  - This is only an example, your paths will differ.
 
 ```yaml
- volumes:
+volumes:
       - /volume1/app_storage/netalertx:/data
 ```
 
-![Adjusting docker-compose](./img/SYNOLOGY/08_Adjust_docker_compose_volumes.png)
+  ![Adjusting docker-compose](./img/SYNOLOGY/08_Adjust_docker_compose_volumes.png)
 
-8. (optional) Change the port number from `20211` to an unused port if this port is already used.
-9. Build the project:
+4. (optional) Change the port number from `20211` to an unused port if this port is already used.
+5. Build the project:
 
-![Build](./img/SYNOLOGY/09_Run_and_build.png)
+  ![Build](./img/SYNOLOGY/09_Run_and_build.png)
 
 10. Navigate to `<Synology URL>:20211` (or your custom port).
 11. Read the [Subnets](./SUBNETS.md) and [Plugins](/docs/PLUGINS.md) docs to complete your setup.
 
+## Solving permission issues
+
+  See also the [Permission overview guide](./FILE_PERMISSIONS.md).
+
+### Configuring the permissions via SSH
 
 > [!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).
@@ -86,3 +92,31 @@ services:
 >
 >  `sudo chmod -R a+rwx  /local_data_dir`
 >
+
+### Configuring the permissions via the Synology UI
+
+You can also execute the above bash commands via the UI by creating a one-off scheduled task.
+
+1. Control panel -> Task Scheduler
+2. Create -> Scheduled Task -> User-defined Script
+
+  ![User-defined Script](./img/SYNOLOGY/11_permissions_create_scheduled_task.png)
+
+3. Give your task a name.
+
+  ![User-defined task_general](./img/SYNOLOGY/12_permissions_task_general.png)
+
+4. Specify one-off execution time (e.g. 5 minutes from now).
+
+  ![task_schedule](./img/SYNOLOGY/13_permissions_task_schedule.png)
+
+5. Paste the commands from the above SSH section and replace the `/local_data_dir` with the parent fodler of your `/db` and `/config` folders.
+
+  ![task_settings](./img/SYNOLOGY/14_permissions_task_settings.png)
+
+6. Wait until the execution time passes and verify the new ownership.
+
+  ![permissions_after](./img/SYNOLOGY/15_permissions_after.png)
+
+
+In case of issues, double-check the [Permission overview guide](./FILE_PERMISSIONS.md).

install/production-filesystem/entrypoint.d/20-first-run-db.sh

@@ -1,32 +1,57 @@
 #!/bin/sh
-# This script checks if the database file exists, and if not, creates it with the initial schema.
-# It is intended to be run at the first start of the application.
+# Ensures the database exists, or creates a new one on first run.
+# Intended to run only at initial startup.
 
-# If ALWAYS_FRESH_INSTALL is true, remove the database to force a rebuild.
-if [ "${ALWAYS_FRESH_INSTALL}" = "true" ]; then
-    if [ -f "${NETALERTX_DB_FILE}" ]; then
-        # Provide feedback to the user.
-        >&2 echo "INFO: ALWAYS_FRESH_INSTALL is true. Removing existing database to force a fresh installation."
-        rm -f "${NETALERTX_DB_FILE}" "${NETALERTX_DB_FILE}-shm" "${NETALERTX_DB_FILE}-wal"
+set -eu
+
+YELLOW=$(printf '\033[1;33m')
+CYAN=$(printf '\033[1;36m')
+RED=$(printf '\033[1;31m')
+RESET=$(printf '\033[0m')
+
+# Ensure DB folder exists
+if [ ! -d "${NETALERTX_DB}" ]; then
+    if ! mkdir -p "${NETALERTX_DB}"; then
+        >&2 printf "%s" "${RED}"
+        >&2 cat <<EOF
+══════════════════════════════════════════════════════════════════════════════
+❌  Error creating DB folder in: ${NETALERTX_DB}
+
+A database directory is required for proper operation, however there appear to be
+insufficient permissions on this mount or it is otherwise inaccessible.
+
+More info: https://github.com/jokob-sk/NetAlertX/blob/main/docs/FILE_PERMISSIONS.md
+══════════════════════════════════════════════════════════════════════════════
+EOF
+        >&2 printf "%s" "${RESET}"
+        exit 1
     fi
-# Otherwise, if the db exists, exit.
-elif [ -f "${NETALERTX_DB_FILE}" ]; then
+    chmod 700 "${NETALERTX_DB}" 2>/dev/null || true
+fi
+
+# Fresh rebuild requested
+if [ "${ALWAYS_FRESH_INSTALL:-false}" = "true" ] && [ -f "${NETALERTX_DB_FILE}" ]; then
+    >&2 echo "INFO: ALWAYS_FRESH_INSTALL enabled — removing existing database."
+    rm -f "${NETALERTX_DB_FILE}" "${NETALERTX_DB_FILE}-shm" "${NETALERTX_DB_FILE}-wal"
+fi
+
+# If file exists now, nothing to do
+if [ -f "${NETALERTX_DB_FILE}" ]; then
     exit 0
 fi
 
-CYAN=$(printf '\033[1;36m')
-RESET=$(printf '\033[0m')
 >&2 printf "%s" "${CYAN}"
 >&2 cat <<EOF
 ══════════════════════════════════════════════════════════════════════════════
-🆕  First run detected. Building initial database schema in ${NETALERTX_DB_FILE}.
+🆕  First run detected — building initial database at: ${NETALERTX_DB_FILE}
 
-    Do not interrupt this step. Once complete, consider backing up the fresh
-    database before onboarding sensitive networks.
+    Do not interrupt this step. When complete, consider backing up the fresh
+    DB before onboarding sensitive or critical networks.
 ══════════════════════════════════════════════════════════════════════════════
 EOF
 >&2 printf "%s" "${RESET}"
 
+
 # Write all text to db file until we see "end-of-database-schema"
 sqlite3 "${NETALERTX_DB_FILE}" <<'end-of-database-schema'
 CREATE TABLE Events (eve_MAC STRING (50) NOT NULL COLLATE NOCASE, eve_IP STRING (50) NOT NULL COLLATE NOCASE, eve_DateTime DATETIME NOT NULL, eve_EventType STRING (30) NOT NULL COLLATE NOCASE, eve_AdditionalInfo STRING (250) DEFAULT (''), eve_PendingAlertEmail BOOLEAN NOT NULL CHECK (eve_PendingAlertEmail IN (0, 1)) DEFAULT (1), eve_PairEventRowid INTEGER);

install/production-filesystem/entrypoint.d/31-apply-conf-override.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+# override-config.sh - Handles APP_CONF_OVERRIDE environment variable
+
+OVERRIDE_FILE="${NETALERTX_CONFIG}/app_conf_override.json"
+
+# Ensure config directory exists
+mkdir -p "$(dirname "$NETALERTX_CONFIG")" || {
+    >&2 echo "ERROR: Failed to create config directory $(dirname "$NETALERTX_CONFIG")"
+    exit 1
+}
+
+# Remove old override file if it exists
+rm -f "$OVERRIDE_FILE"
+
+# Check if APP_CONF_OVERRIDE is set
+if [ -z "$APP_CONF_OVERRIDE" ]; then
+    >&2 echo "APP_CONF_OVERRIDE is not set. Skipping override config file creation."
+else
+    # Save the APP_CONF_OVERRIDE env variable as a JSON file
+    echo "$APP_CONF_OVERRIDE" > "$OVERRIDE_FILE" || {
+        >&2 echo "ERROR: Failed to write override config to $OVERRIDE_FILE"
+        exit 2
+    }
+
+    RESET=$(printf '\033[0m')
+    >&2 cat <<EOF
+══════════════════════════════════════════════════════════════════════════════
+📝  APP_CONF_OVERRIDE detected. Configuration written to $OVERRIDE_FILE.
+
+    Make sure the JSON content is correct before starting the application.
+══════════════════════════════════════════════════════════════════════════════
+EOF
+
+    >&2 printf "%s" "${RESET}"
+fi

install/production-filesystem/entrypoint.d/99-ports-available.sh

@@ -5,22 +5,22 @@
 
 # Define ports from ENV variables, applying defaults
 PORT_APP=${PORT:-20211}
-PORT_GQL=${APP_CONF_OVERRIDE:-${GRAPHQL_PORT:-20212}}
+# PORT_GQL=${APP_CONF_OVERRIDE:-${GRAPHQL_PORT:-20212}}
 
-# Check if ports are configured to be the same
-if [ "$PORT_APP" -eq "$PORT_GQL" ]; then
-    cat <<EOF
-══════════════════════════════════════════════════════════════════════════════
-⚠️  Configuration Warning: Both ports are set to ${PORT_APP}.
+# # Check if ports are configured to be the same
+# if [ "$PORT_APP" -eq "$PORT_GQL" ]; then
+#     cat <<EOF
+# ══════════════════════════════════════════════════════════════════════════════
+# ⚠️  Configuration Warning: Both ports are set to ${PORT_APP}.
 
-    The Application port (\$PORT) and the GraphQL API port
-    (\$APP_CONF_OVERRIDE or \$GRAPHQL_PORT) are configured to use the
-    same port. This will cause a conflict.
+#     The Application port (\$PORT) and the GraphQL API port
+#     (\$APP_CONF_OVERRIDE or \$GRAPHQL_PORT) are configured to use the
+#     same port. This will cause a conflict.
 
-    https://github.com/jokob-sk/NetAlertX/blob/main/docs/docker-troubleshooting/port-conflicts.md
-══════════════════════════════════════════════════════════════════════════════
-EOF
-fi
+#     https://github.com/jokob-sk/NetAlertX/blob/main/docs/docker-troubleshooting/port-conflicts.md
+# ══════════════════════════════════════════════════════════════════════════════
+# EOF
+# fi
 
 # Check for netstat (usually provided by busybox)
 if ! command -v netstat >/dev/null 2>&1; then
@@ -53,17 +53,17 @@ if echo "$LISTENING_PORTS" | grep -q ":${PORT_APP}$"; then
 EOF
 fi
 
-# Check GraphQL Port
-# We add a check to avoid double-warning if ports are identical AND in use
-if [ "$PORT_APP" -ne "$PORT_GQL" ] && echo "$LISTENING_PORTS" | grep -q ":${PORT_GQL}$"; then
-    cat <<EOF
-══════════════════════════════════════════════════════════════════════════════
-⚠️  Port Warning: GraphQL API port ${PORT_GQL} is already in use.
+# # Check GraphQL Port
+# # We add a check to avoid double-warning if ports are identical AND in use
+# if [ "$PORT_APP" -ne "$PORT_GQL" ] && echo "$LISTENING_PORTS" | grep -q ":${PORT_GQL}$"; then
+#     cat <<EOF
+# ══════════════════════════════════════════════════════════════════════════════
+# ⚠️  Port Warning: GraphQL API port ${PORT_GQL} is already in use.
 
-    The GraphQL API (defined by \$APP_CONF_OVERRIDE or \$GRAPHQL_PORT)
-    may fail to start.
+#     The GraphQL API (defined by \$APP_CONF_OVERRIDE or \$GRAPHQL_PORT)
+#     may fail to start.
 
-    https://github.com/jokob-sk/NetAlertX/blob/main/docs/docker-troubleshooting/port-conflicts.md
-══════════════════════════════════════════════════════════════════════════════
-EOF
-fi
+#     https://github.com/jokob-sk/NetAlertX/blob/main/docs/docker-troubleshooting/port-conflicts.md
+# ══════════════════════════════════════════════════════════════════════════════
+# EOF
+# fi