Merge pull request #1603 from netalertx/main

sync

Author: jokob-sk

.github/workflows/mkdocs.yml

@@ -25,7 +25,8 @@ jobs:
           pip install \
             mkdocs==1.6.0 \
             mkdocs-material==9.5.21 \
-            mkdocs-github-admonitions-plugin==0.1.1
+            mkdocs-github-admonitions-plugin==0.1.1 \
+            mkdocs-glightbox
 
       - name: Build MkDocs
         run: mkdocs build

CONTRIBUTING.md

@@ -15,6 +15,22 @@ Before opening a new issue:
 - [Check Common Issues & Debug Tips](https://docs.netalertx.com/DEBUG_TIPS#common-issues)
 - [Search Closed Issues](https://github.com/netalertx/NetAlertX/issues?q=is%3Aissue+is%3Aclosed)
 
+---
+
+## Contributing without coding knowledge
+
+Writing code is not the only way how you can contribute to the project. Here are some ideas how you can help out otherwise:
+
+ - Help improving the documentation (text, typos, use cases, screenshots - all this makes things better)
+ - Share your favorite project on socials (see [Growth ideas](./GROWTH.md))
+ - Write a blog post, or a how-to set-up guide
+ - Write how it helped you to achieve something fun or interesting to simplify your personal or work life
+ - Help with the translation effort
+ - Running a nightly or dev build to test for bugs before they make it to the production release
+ - Report bugs and features with sufficient detail and care (super important to ease everyone's maintenance burden and minimize back-and-forth)
+ - running a projects test suite
+
+
 ---
 
 ## Use of AI

GROWTH.md

@@ -0,0 +1,142 @@
+# 📈 NetAlertX Growth Playbook
+
+If you like NetAlertX and want to help it grow, this is how.
+
+This isn’t about spam or "growth hacks." It’s just getting the tool in front of people who already have the problem (manual network docs, blind spots, messy networks).
+
+---
+
+## 🎯 Who this is for
+
+* **Homelabbers** → Proxmox, Unraid, Raspberry Pi setups
+* **Self-hosters** → moving away from cloud / want local-first
+* **Sysadmins / MSPs** → need visibility + fast onboarding
+
+---
+
+## 💬 Where to post (and how)
+
+### Reddit (main channel)
+
+Reddit works *if* you don’t sound like marketing.
+
+**Subreddits**
+
+* r/homelab
+* r/selfhosted
+* r/sysadmin
+* r/networking
+
+**What works**
+
+* "Show r/homelab" / "I built this"
+* Problem → solution
+* Real screenshots or short GIFs
+
+**Example**
+
+> Tired of keeping network diagrams up to date?
+> I deployed something that does it automatically.
+
+**Avoid**
+
+* Over-explaining
+* Buzzwords
+* "Check out my project!!!" energy
+
+**Timing (rough guide)**
+
+* Tue–Thu mornings (US time)
+
+---
+
+### Hacker News (Show HN)
+
+Good fit because NetAlertX is:
+
+* local-first
+* privacy-focused
+* actually useful
+
+**Title**
+
+> Show HN: NetAlertX – network documentation that updates itself
+
+Be ready to answer:
+
+* stack (Python / PHP / JS)
+* how discovery works
+* privacy / local scanning
+
+---
+
+### Awesome Lists
+
+Low effort, long-term visibility.
+
+Target:
+
+* awesome-selfhosted
+* awesome-homelab
+
+Keep it simple:
+
+> NetAlertX – automated network discovery and documentation with alerting
+
+---
+
+## 🎥 Content / creators
+
+If you or someone else makes videos, these angles work:
+
+* **First 5 minutes** → "it already found everything"
+* **Before vs after** → manual vs NetAlertX
+* **Docker setup** → show how easy it is
+
+No need for overproduction—real usage > polished demos.
+
+---
+
+## ⚖️ Positioning (keep it simple)
+
+When explaining NetAlertX, this is the mental model:
+
+|         | Manual Docs       | Basic Scanners | NetAlertX                 |
+| ------- | ----------------- | -------------- | ------------------------- |
+| Updates | Manual / outdated | On demand      | **Automatic**             |
+| Alerts  | None              | Limited        | **New / unknown devices** |
+| History | None              | None           | **Device timeline**       |
+| Effort  | High              | Medium         | **Set & forget**          |
+
+---
+
+## 🧑‍💻 MSP / professional angle
+
+If you’re using it in real environments:
+
+* Faster client onboarding
+* Better visibility
+* Less "what changed?" guessing
+
+That’s the value—keep it grounded. And share your experience 🙏
+
+---
+
+## 🛠 Easy ways to help
+
+* Star the repo
+* Post a screenshot of your network
+* Mention it when someone asks "how do you track devices?" or "how do you detect presence?"
+* Write a quick "how I use it" post
+
+---
+
+## Final note
+
+Authenticity matters more than reach.
+
+If it feels like marketing, people ignore it.
+If it feels like "this solved my problem," people pay attention.
+
+Thanks a lot in advance!
+                        - jokob

docs/PLUGINS.md

@@ -57,6 +57,7 @@ Device-detecting plugins insert values into the `CurrentScan` database table.  T
 | `DHCPSRVS`      | [dhcp_servers](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/dhcp_servers/)                       | ♻        | DHCP servers                              |          |          |
 | `DIGSCAN`       | [dig_scan](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/dig_scan/)                               | 🆎       | Dig (DNS) Name resolution                 |          |          |
 | `FREEBOX`       | [freebox](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/freebox/)                                  | 🔍/♻/🆎  | Pull data and names from Freebox/Iliadbox |          |          |
+| `FRITZBOX`      | [fritzbox](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/fritzbox/)                                | 🔍       | Fritz!Box device scanner via TR-064       |          |          |
 | `ICMP`          | [icmp_scan](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/icmp_scan/)                             | ♻        | ICMP (ping) status checker                |          |          |
 | `INTRNT`        | [internet_ip](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/internet_ip/)                         | 🔍       | Internet IP scanner                       |          |          |
 | `INTRSPD`       | [internet_speedtest](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/internet_speedtest/)           | ♻        | Internet speed test                       |          |          |

docs/REMOTE_NETWORKS.md

@@ -33,27 +33,27 @@ VPNs use virtual interfaces (e.g., `tun0`, `tap0`) to encapsulate traffic, bypas
 
 > **Possible workaround**: Configure the VPN to bridge networks instead of routing to enable ARP, though this depends on the VPN setup and security requirements.
 
-# Other Workarounds
+## Other Workarounds
 
 The following workarounds should work for most complex network setups.
 
-## Supplementing Plugins
+### Supplementing Plugins
 
 You can use supplementary plugins that employ alternate methods. Protocols used by the `SNMPDSC` or `DHCPLSS` plugins are widely supported on different routers and can be effective as workarounds. Check the [plugins list](./PLUGINS.md) to find a plugin that works with your router and network setup.
 
-## Multiple NetAlertX Instances
+### Multiple NetAlertX Instances
 
 If you have servers in different networks, you can set up separate NetAlertX instances on those subnets and synchronize the results into one instance using the [`SYNC` plugin](https://github.com/netalertx/NetAlertX/tree/main/front/plugins/sync).
 
-## Manual Entry
+### Manual Entry
 
 If you don't need to discover new devices and only need to report on their status (`online`, `offline`, `down`), you can manually enter devices and check their status using the [`ICMP` plugin](https://github.com/netalertx/NetAlertX/blob/main/front/plugins/icmp_scan/), which uses the `ping` command internally.
 
 For more information on how to add devices manually (or dummy devices), refer to the [Device Management](./DEVICE_MANAGEMENT.md) documentation.
 
 To create truly dummy devices, you can use a loopback IP address (e.g., `0.0.0.0` or `127.0.0.1`) or the `Force Status` field so they appear online.
 
-## NMAP and Fake MAC Addresses
+### NMAP and Fake MAC Addresses
 
 Scanning remote networks with NMAP is possible (via the `NMAPDEV` plugin), but since it cannot retrieve the MAC address, you need to enable the `NMAPDEV_FAKE_MAC` setting. This will generate a fake MAC address based on the IP address, allowing you to track devices. However, this can lead to inconsistencies, especially if the IP address changes or a previously logged device is rediscovered. If this setting is disabled, only the IP address will be discovered, and devices with missing MAC addresses will be skipped.
 

docs/SUBNETS.md

@@ -8,8 +8,15 @@ You need to specify the network interface and the network mask. You can also con
 > If you don't see all expected devices run the following command in the NetAlertX container (replace the interface and ip mask):
 > `sudo arp-scan --interface=eth0 192.168.1.0/24`
 >
->  If this command returns no results, the network is not accessible due to your network or firewall restrictions (Wi-Fi Extenders, VPNs and inaccessible networks). If direct scans are not possible, check the [remote networks documentation](./REMOTE_NETWORKS.md) for workarounds.
-
+>  If this command returns no results:
+>
+> - ✅ If you see output like `IPv4: (none)` or `Using 0.0.0.0`:
+>   - The interface was not detected correctly.
+>   - Fix: explicitly set the interface using `--interface=<name>`.
+>
+> - ❌ If the scan runs correctly but still finds no devices:
+>   - The network may not be accessible due to firewall, VLAN, or network restrictions (Wi-Fi extenders, VPNs, etc.).
+>   - If direct scans are not possible, check the [remote networks documentation](./REMOTE_NETWORKS.md) for workarounds.
 
 ## Example Values
 

docs/WORKFLOWS.md

@@ -1,10 +1,10 @@
 # Workflows Overview
 
-The workflows module in allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
+The workflows module allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.
 
 ![Workflows diagram](./img/WORKFLOWS/workflows_diagram.png)
 
-Below are a few examples that demonstrate how this module can be used to simplify network management tasks.
+You can find a couple of use case examples in [Workflow Examples](WORKFLOW_EXAMPLES.md).
 
 ## Updating Workflows
 

front/js/app-init.js

@@ -126,7 +126,7 @@ function isAppInitialized() {
 
   lang_shouldBeCompletedCalls = getLangCode() == 'en_us' ? 1 : 2;
 
-  // check if each ajax call completed succesfully
+  // check if each ajax call completed successfully
   for (const call_name of completedCalls_final) {
     if (getCache(CACHE_KEYS.initFlag(call_name)) != "true") {
       _isAppInitLog(`[isAppInitialized] waiting on ${call_name} (value: ${getCache(CACHE_KEYS.initFlag(call_name))})`);
@@ -268,7 +268,7 @@ setTimeout(() => {
   // page refresh if configured
   const refreshTime = getSetting("UI_REFRESH");
   if (refreshTime && refreshTime !== "0" && refreshTime !== "") {
-    console.log("Refreshing page becasue UI_REFRESH setting enabled.");
+    console.log("Refreshing page because UI_REFRESH setting enabled.");
     newTimerRefreshData(clearCache, parseInt(refreshTime)*1000);
   }
 

front/js/ui_components.js

@@ -590,6 +590,7 @@ function addOptionFromModalInput() {
  * A MAC is considered fake if it starts with:
  *   - "FA:CE" (new synthetic devices)
  *   - "00:1A" (legacy placeholder devices)
+ *   - "02:" (legacy placeholder devices)
  *
  * The check is case-insensitive.
  *
@@ -600,8 +601,8 @@ function isFakeMac(macAddress) {
   // Normalize to lowercase for consistent comparison
   macAddress = macAddress.toLowerCase();
 
-  // Check if MAC starts with FA:CE or 00:1a
-  return macAddress.startsWith("fa:ce") || macAddress.startsWith("00:1a");
+  // Check if MAC starts with FA:CE or 00:1a or 02:
+  return macAddress.startsWith("fa:ce") || macAddress.startsWith("00:1a") || macAddress.startsWith("02:");
 }
 
 

front/php/templates/language/ar_ar.json

@@ -805,4 +805,4 @@
     "settings_system_label": "نظام",
     "settings_update_item_warning": "قم بتحديث القيمة أدناه. احرص على اتباع التنسيق السابق. <b>لم يتم إجراء التحقق.</b>",
     "test_event_tooltip": "احفظ التغييرات أولاً قبل اختبار الإعدادات."
-}
+}