NetAlertX/front/plugins/sync/README.md

Overview

The synchronization plugin is designed to synchronize data across multiple instances of the app. It supports the following data synchronization modes:

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

This plugin is usually used if you need to monitor inaccessible networks (WAN, VLAN etc.). Read the Remote networks documentation for more details about these scenarios.

Synchronization Modes

The plugin operates in three different modes based on the configuration settings.

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.

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.

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.

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.

Settings

Node (Source) Settings [n]

• API Token [n,h]: API_TOKEN (has to be same across all nodes)

• When to Run [n,h]: SYNC_RUN

• Schedule [n,h]: SYNC_RUN_SCHD

• 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]

• API Token [n,h]: API_TOKEN (has to be same across all nodes)

• When to Run [n,h]: SYNC_RUN

• Schedule [n,h]: SYNC_RUN_SCHD

• Encryption Key [n,h]: SYNC_encryption_key

• Nodes to Pull From [h]: SYNC_nodes

Usage

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

• 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.

Example use case: Network Setup with Multiple VLANs and VM Scanning

Thank you to @richtj999 for the use case 🙏

I have 6 VLANs, all isolated by a firewall, except for one VLAN that has access to all the others.

Initially, I had one virtual machine (VM) with 6 network cards, one for each VLAN. While this setup worked, it introduced delays due to other concurrent scans. To optimize this, I switched to a multi-VM setup:

• I created 6 VMs, each attached to a single VLAN.
• One VM acts as the "server," and the other 5 as "clients."
• The server has access to all VLANs (via firewall rules) and collects data from the client VMs, which each scan their own VLAN.

Summary

• Single VM on six VLANs: Slower because one VM scans all networks.
• Six VMs on six VLANs: Faster because each VM scans its own network, sending the results to the server.

Example Setup

• VM1 ("Server"): Network 1 (can access all networks) - IP: 10.10.10.106
  Receives data from all NetAlertX clients and scans network 1.

• VM2 ("Client"): Network 2 (can access only network 2) - IP: 192.168.x.x
  Scans network 2; VM1 retrieves this data.

• VM3 ("Client"): Network 3 (can access only network 3) - IP: 192.168.x.x
  Scans network 3; VM1 retrieves this data.

• VM4 ("Client"): Network 4 (can access only network 4) - IP: 192.168.x.x
  Scans network 4; VM1 retrieves this data.

• VM5 ("Client"): Network 5 (can access only network 5) - IP: 192.168.x.x
  Scans network 5; VM1 retrieves this data.

• VM6 ("Client"): Network 6 (can access only network 6) - IP: 192.168.x.x
  Scans network 6; VM1 retrieves this data.

---

How to Set It Up

Server (VM1)

1. Go to Settings > System > Sync Hub.
2. Set the schedule (5 minutes works for me).
3. API Token: Use any string, but it must match the clients (e.g., abc123).
4. Encryption Key: Use any string, but it must match the clients (e.g., abc123).
5. Under Nodes, add the full URL for each client, e.g., http://192.168.1.20.20211/.
6. Node Name: Leave blank.
7. Check Sync Devices.

Clients (VM2, VM3, VM4, VM5, VM6)

1. Go to Settings > System > Sync Hub.
2. Set When to run to "Always after scan."
3. API Token: Use the same token as the server (e.g., abc123).
4. Encryption Key: Use the same key as the server (e.g., abc123).
5. Leave Nodes blank.
6. Set Node Name to a unique, memorable name for each client.
7. Check Sync Devices.