Merge pull request #1552 from MrMeatikins/fix-arp-flux-docs-issue-1546

docs: Clarify ARP flux sysctl limitations with host networking

Author: jokob-sk

docs/DOCKER_COMPOSE.md

@@ -30,6 +30,14 @@ 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
+    # --- ARP FLUX MITIGATION ---
+    # Note: When using `network_mode: host`, these sysctls require the
+    # NET_ADMIN capability to be applied to the host namespace.
+    # 
+    # If your environment restricts capabilities, or you prefer to configure
+    # them on the Host OS, REMOVE the sysctls block below and apply via:
+    # sudo sysctl -w net.ipv4.conf.all.arp_ignore=1 net.ipv4.conf.all.arp_announce=2
+    # ---------------------------
     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

docs/docker-troubleshooting/arp-flux-sysctls.md

@@ -21,7 +21,9 @@ The running environment does not provide the expected kernel sysctl values. This
 
 ## How to Correct the Issue
 
-Set these sysctls at container runtime.
+### Option A: Via Docker (Standard Bridge Networking or `network_mode: host` with `NET_ADMIN`)
+
+If you are using standard bridged networking, or `network_mode: host` and the container is granted the `NET_ADMIN` capability (as is the default recommendation), set these sysctls at container runtime.
 
 - In `docker-compose.yml` (preferred):
   ```yaml
@@ -44,6 +46,24 @@ Set these sysctls at container runtime.
 > - Use `--privileged` with `docker run`.
 > - Use the more restrictive `--cap-add=NET_ADMIN` (or `cap_add: [NET_ADMIN]` in `docker-compose` service definitions) to allow the sysctls to be applied at runtime.
 
+### Option B: Via Host OS (Fallback for `network_mode: host`)
+
+If you are running the container with `network_mode: host` and cannot grant the `NET_ADMIN` capability, or if your container runtime environment explicitly blocks sysctl overrides, applying these settings via the container configuration will fail. Attempting to do so without sufficient privileges typically results in an OCI runtime error: `sysctl "net.ipv4.conf.all.arp_announce" not allowed in host network namespace`.
+
+In this scenario, you must apply the settings directly on your host operating system:
+
+1. **Remove** the `sysctls` section from your `docker-compose.yml`.
+2. **Apply** on the host immediately:
+   ```bash
+   sudo sysctl -w net.ipv4.conf.all.arp_ignore=1
+   sudo sysctl -w net.ipv4.conf.all.arp_announce=2
+   ```
+3. **Make persistent** by adding the following lines to `/etc/sysctl.conf` on the host:
+   ```text
+   net.ipv4.conf.all.arp_ignore=1
+   net.ipv4.conf.all.arp_announce=2
+   ```
+
 ## Additional Resources
 
 For broader Docker Compose guidance, see:

install/production-filesystem/entrypoint.d/37-host-optimization.sh

@@ -22,6 +22,11 @@ if [ "$failed" -eq 1 ]; then
       net.ipv4.conf.all.arp_ignore=1
       net.ipv4.conf.all.arp_announce=2
 
+    Note: If using 'network_mode: host', setting these via docker-compose sysctls
+    requires the NET_ADMIN capability. When granted, these sysctls will
+    modify the host namespace. Otherwise, you must configure them directly
+    on your host operating system instead.
+
     Detection accuracy may be reduced until configured.
 
     See: https://docs.netalertx.com/docker-troubleshooting/arp-flux-sysctls/