📚Docs

2025-12-07 09:36:05 -08:00 · 2024-09-22 17:05:49 +10:00
parent ef458903b7
commit 06e49f7adb
6 changed files with 58 additions and 31 deletions
--- a/docs/BACKUPS.md
+++ b/docs/BACKUPS.md
@@ -8,7 +8,7 @@ There are 3 artifacts that can be used to backup the application:
 | File                  | Description                   | Limitations                   |
 |-----------------------|-------------------------------|-------------------------------|
 | `/db/app.db`       | Database file(s)  | The database file might be in an uncommitted state or corrupted |
-| `/config/app.conf` | Configuration file |   Doesn't contain settings from the Maintenance section        |
+| `/config/app.conf` | Configuration file |  Can be overriden with the [`APP_CONF_OVERRIDE` env variable](https://github.com/jokob-sk/NetAlertX/tree/main/dockerfiles#docker-environment-variables).  |
 | `/config/devices.csv`  | CSV file containing device information |     Doesn't contain historical data        |

 ## Data and backup storage
--- a/front/css/app.css
+++ b/front/css/app.css
@@ -1097,6 +1097,11 @@ input[readonly] {
    display: inline-block;
 }

+#settingsPage  .form-control
+{
+    min-height: 42px;
+}
+
 #settingsPage  .select2-selection
 {
    background-color: rgb(96, 96, 96);
--- a/front/deviceDetails.php
+++ b/front/deviceDetails.php
@@ -1445,10 +1445,10 @@ function setDeviceData (direction='', refreshCallback='') {

  // update data to server
  $.get('php/server/devices.php?action=setDeviceData&mac='+ mac
-    + '&name='           + encodeURIComponent($('#txtName').val())
-    + '&owner='          + encodeURIComponent($('#txtOwner').val())
+    + '&name='           + encodeURIComponent($('#txtName').val().replace(/'/g, ""))
+    + '&owner='          + encodeURIComponent($('#txtOwner').val().replace(/'/g, ""))
    + '&type='           + $('#txtDeviceType').val()
-    + '&vendor='         + encodeURIComponent($('#txtVendor').val())
+    + '&vendor='         + encodeURIComponent($('#txtVendor').val().replace(/'/g, ""))
    + '&icon='           + encodeURIComponent($('#txtIcon').val())
    + '&favorite='       + ($('#chkFavorite')[0].checked * 1)
    + '&group='          + encodeURIComponent($('#txtGroup').val())
--- a/front/index.php
+++ b/front/index.php
@@ -78,7 +78,7 @@ if (isset ($_SESSION["login"]) == FALSE || $_SESSION["login"] != 1)
  <meta http-equiv="Pragma" content="no-cache" />
  <meta http-equiv="Expires" content="0" />
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
-  <title>Net Alert X | Log in</title>
+  <title>NetAlert X | Log in</title>
  <!-- Tell the browser to be responsive to screen width -->
  <meta content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" name="viewport">
  <!-- Bootstrap 3.3.7 -->
@@ -104,7 +104,7 @@ if ($ENABLED_DARKMODE === True) {
 <body class="hold-transition login-page">
 <div class="login-box login-custom">
  <div class="login-logo">
-    <a href="/index2.php">Net <b>Alert</b><sup>x</sup></a>
+    <a href="/index2.php">Net<b>Alert</b><sup>x</sup></a>
  </div>
  <!-- /.login-logo -->
  <div class="login-box-body">
--- a/front/plugins/sync/README.md
+++ b/front/plugins/sync/README.md
@@ -1,41 +1,63 @@
 ## Overview

-Synchronization plugin to synchronize multiple app instances. The Plugin can sychronize 2 types of data:
+The synchronization plugin is designed to synchronize data across multiple instances of the app. It supports the following data synchronization modes:

-1. 💻 Devices: The plugin sends an encrypted `table_devices.json` file to synchronize the whole Devices DB table.
-1. 🔌 Plugin data:  The plugin sends encrypted `last_result.log` files for individual plugins. 
+1. **💻 Devices**: Sends an encrypted `table_devices.json` file to synchronize the entire Devices database table.
+2. **🔌 Plugin Data**: Sends encrypted `last_result.log` files for individual plugins.

-> [!TIP]
-> `[n]` indicates a setting that is usually specified for the node instance. `[n,h]` indicates a setting used both, on the node and on the hub instance.
+> **Note:** `[n]` indicates a setting specified for the node instance, and `[n,h]` indicates a setting used on both the node and the hub instances.

-### Synchronizing 💻 Devices data or 🔌 Plugins data
+### Synchronization Modes

-Most of the setups will probably only use 💻 Devices synchronization. 🔌 Plugins data will be probably used in only special use cases. 
+The plugin operates in three different modes based on the configuration settings:

-#### [n] Node (Source) Settings
+1. **Mode 1: PUSH (NODE)** - Sends data from the node to the hub.
+   - This mode is activated if `SYNC_hub_url` is set and either `SYNC_devices` or `SYNC_plugins` is enabled.
+   - **Actions**:
+     - Sends `table_devices.json` to the hub if `SYNC_devices` is enabled.
+     - Sends individual plugin `last_result.log` files to the hub if `SYNC_plugins` is enabled.

- When to run [n,h] `SYNC_RUN`
- Schedule [n,h] `SYNC_RUN_SCHD`
- API token [n,h] `SYNC_api_token`
- Encryption Key [n,h] `SYNC_encryption_key` 
- Node name [n] `SYNC_node_name`
- Hub URL [n] `SYNC_hub_url`
- Sync Devices [n] `SYNC_devices` or Sync Plugins [n] `SYNC_plugins` (or both)
+2. **Mode 2: PULL (HUB)** - Retrieves data from nodes to the hub.
+   - This mode is activated if `SYNC_nodes` is set.
+   - **Actions**:
+     - Retrieves data from configured nodes using the API and saves it locally for further processing.

-#### [h] Hub (Target) Settings
+3. **Mode 3: RECEIVE (HUB)** - Processes received data on the hub.
+   - Activated when data is received in Mode 2 and is ready to be processed.
+   - **Actions**:
+     - Decodes received data files, processes them, and updates the Devices table accordingly.

- When to run [n,h] `SYNC_RUN`
- Schedule [n,h] `SYNC_RUN_SCHD`
- API token [n,h] `SYNC_api_token`
- Encryption Key [n,h] `SYNC_encryption_key`
+### Settings

+#### Node (Source) Settings `[n]`
+
+- **When to Run** `[n,h]`: `SYNC_RUN`
+- **Schedule** `[n,h]`: `SYNC_RUN_SCHD`
+- **API Token** `[n,h]`: `SYNC_api_token`
+- **Encryption Key** `[n,h]`: `SYNC_encryption_key`
+- **Node Name** `[n]`: `SYNC_node_name`
+- **Hub URL** `[n]`: `SYNC_hub_url`
+- **Sync Devices** `[n]`: `SYNC_devices`
+- **Sync Plugins** `[n]`: `SYNC_plugins`
+
+#### Hub (Target) Settings `[h]`
+
+- **When to Run** `[n,h]`: `SYNC_RUN`
+- **Schedule** `[n,h]`: `SYNC_RUN_SCHD`
+- **API Token** `[n,h]`: `SYNC_api_token`
+- **Encryption Key** `[n,h]`: `SYNC_encryption_key`
+- **Nodes to Pull From** `[h]`: `SYNC_nodes`

 ### Usage

- Head to **Settings** > **Sync Hub** to adjust the default values.
+1. **Adjust Settings**:
+   - Navigate to **Settings** > **Sync Hub** to modify default settings.
+2. **Data Flow**:
+   - Nodes send or receive data based on the specified modes, either pushing data to the hub or pulling from nodes.

 ### Notes

- If a MAC address already exists on the hub, the device will be skipped in the data coming from this SYNC plugin. 
+- Existing devices on the hub will not be updated by the data received from this SYNC plugin if their MAC addresses are already present.
+- It is recommended to use Device synchronization primarily. Plugin data synchronization is more suitable for specific use cases.

-![Syn Hub Setup Diagram](/front/plugins/sync/sync_hub.png)
+![Sync Hub Setup Diagram](/front/plugins/sync/sync_hub.png)
--- a/front/plugins/ui_settings/config.json
+++ b/front/plugins/ui_settings/config.json
@@ -166,12 +166,12 @@
        "PGkgY2xhc3M9J2ZhIGZhLXdpZmknPjwvaT4=",
        "PGkgY2xhc3M9ImZhIGZhLWNvbXB1dGVyIj48L2k+",
        "PGkgY2xhc3M9ImZhIGZhLWV0aGVybmV0Ij48L2k+",
-        "PGkgY2xhc3M9ImZhIGZhLWdhbWVwYWQiPjwvaT4",
+        "PGkgY2xhc3M9ImZhIGZhLWdhbWVwYWQiPjwvaT4=",
        "PGkgY2xhc3M9ImZhIGZhLWdsb2JlIj48L2k+",
        "PGkgY2xhc3M9ImZhIGZhLWxhcHRvcCI+PC9pPg==",
        "PGkgY2xhc3M9ImZhIGZhLWxpZ2h0YnVsYiI+PC9pPg==",
        "PGkgY2xhc3M9ImZhIGZhLXNoaWVsZCI+PC9pPg==",
-        "PGkgY2xhc3M9ImZhIGZhLXdpZmkiPjwvaT4",
+        "PGkgY2xhc3M9ImZhIGZhLXdpZmkiPjwvaT4=",
        "PGkgY2xhc3M9J2ZhIGZhLWdhbWVwYWQnPjwvaT4"
      ],
      "options": [],