docs: clarify ARP flux sysctl limitations with host networking

Author: MrMeatikins

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: If running in `network_mode: host`, modern Docker/runc will correctly
+    # block sysctl overrides via the container configuration to prevent 
+    # unauthorized changes to the host's global kernel settings.
+    # 
+    # If using host networking, REMOVE the sysctls block below and apply 
+    # settings directly on your Host OS instead (sudo sysctl -w ...).
+    # ---------------------------
     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)
+
+If you are using standard bridged networking (default), 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 (Required for `network_mode: host`)
+
+If you are running the container with `network_mode: host`, modern Docker versions (specifically the `runc` runtime) **will not allow** you to set `net.*` sysctls via the container configuration. Attempting to do so will result 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,9 @@ 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', you cannot set these via docker-compose
+    sysctls. 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/