From 8ab9d9f3951aa1bea9cfae86fdaefb4e03af535c Mon Sep 17 00:00:00 2001
From: Adam Outler <adamoutler@gmail.com>
Date: Mon, 2 Mar 2026 19:43:38 +0000
Subject: [PATCH] Update docs

---
 docs/DOCKER_COMPOSE.md                        |  3 ++
 .../arp-flux-sysctls.md                       | 47 +++++++++++++++++++
 mkdocs.yml                                    |  1 +
 3 files changed, 51 insertions(+)
 create mode 100644 docs/docker-troubleshooting/arp-flux-sysctls.md

diff --git a/docs/DOCKER_COMPOSE.md b/docs/DOCKER_COMPOSE.md
index dd89807b..e76f08e1 100755
--- a/docs/DOCKER_COMPOSE.md
+++ b/docs/DOCKER_COMPOSE.md
@@ -30,6 +30,9 @@ services:
       - CHOWN                                       # Required for root-entrypoint to chown /data + /tmp before dropping privileges
       - SETUID                                      # Required for root-entrypoint to switch to non-root user
       - SETGID                                      # Required for root-entrypoint to switch to non-root group
+    sysctls:                                        # ARP flux mitigation (reduces duplicate/ambiguous ARP behavior on host networking)
+      net.ipv4.conf.all.arp_ignore: 1
+      net.ipv4.conf.all.arp_announce: 2
 
     volumes:
       - type: volume                                # Persistent Docker-managed named volume for config + database
diff --git a/docs/docker-troubleshooting/arp-flux-sysctls.md b/docs/docker-troubleshooting/arp-flux-sysctls.md
new file mode 100644
index 00000000..d73c5cb0
--- /dev/null
+++ b/docs/docker-troubleshooting/arp-flux-sysctls.md
@@ -0,0 +1,47 @@
+# ARP Flux Sysctls Not Set
+
+## Issue Description
+
+NetAlertX detected that ARP flux protection sysctls are not set as expected:
+
+- `net.ipv4.conf.all.arp_ignore=1`
+- `net.ipv4.conf.all.arp_announce=2`
+
+## Security Ramifications
+
+This is not a direct container breakout risk, but detection quality can degrade:
+
+- Incorrect IP/MAC associations
+- Device state flapping
+- Unreliable topology or presence data
+
+## Why You're Seeing This Issue
+
+The running environment does not provide the expected kernel sysctl values. This is common in Docker setups where sysctls were not explicitly configured.
+
+## How to Correct the Issue
+
+Set these sysctls at container runtime.
+
+- In `docker-compose.yml` (preferred):
+  ```yaml
+  services:
+    netalertx:
+      sysctls:
+        net.ipv4.conf.all.arp_ignore: 1
+        net.ipv4.conf.all.arp_announce: 2
+  ```
+
+- For `docker run`:
+  ```bash
+  docker run \
+    --sysctl net.ipv4.conf.all.arp_ignore=1 \
+    --sysctl net.ipv4.conf.all.arp_announce=2 \
+    jokob-sk/netalertx:latest
+  ```
+
+## Additional Resources
+
+For broader Docker Compose guidance, see:
+
+- [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)
diff --git a/mkdocs.yml b/mkdocs.yml
index 3f7690bc..3aff97cf 100755
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -20,6 +20,7 @@ nav:
         - Docker Updates: UPDATES.md
         - Docker Maintenance: DOCKER_MAINTENANCE.md
       - Docker Startup Troubleshooting:
+        - ARP flux sysctls: docker-troubleshooting/arp-flux-sysctls.md
         - Aufs capabilities: docker-troubleshooting/aufs-capabilities.md
         - Excessive capabilities: docker-troubleshooting/excessive-capabilities.md
         - File permissions: docker-troubleshooting/file-permissions.md